From 6b8ce92d88adab9a7f0ec6502743ed501b95eabb Mon Sep 17 00:00:00 2001 From: baldurk Date: Mon, 7 Dec 2020 12:42:35 +0000 Subject: [PATCH] Clean up docstrings in python interfaces to be strictly typed/formatted * Also added a script that can run as part of CI to verify that the docstring matches, by generating a regex from the docstring documented parameter types and return type and making sure we find a match within the C headers. This ensures all parameters are documented with the right types, no extra parameters are documented, and the return type is correct. * The script also checks proper scoping so that if qrenderdoc docstrings mention a renderdoc type, they need to scope it properly. --- .github/workflows/ci.yml | 1 + docs/verify-docstrings.py | 309 +++++++++++ qrenderdoc/Code/CaptureContext.cpp | 7 +- qrenderdoc/Code/CaptureContext.h | 6 +- qrenderdoc/Code/Interface/Extensions.h | 99 ++-- qrenderdoc/Code/Interface/PersistantConfig.h | 45 +- qrenderdoc/Code/Interface/QRDInterface.h | 527 +++++++++++-------- qrenderdoc/Code/Interface/RemoteHost.h | 80 ++- qrenderdoc/Code/MiniQtHelper.cpp | 14 +- qrenderdoc/Code/MiniQtHelper.h | 14 +- qrenderdoc/Code/pyrenderdoc/renderdoc.i | 11 +- qrenderdoc/Windows/BufferViewer.cpp | 8 +- qrenderdoc/Windows/BufferViewer.h | 8 +- qrenderdoc/Windows/PythonShell.cpp | 21 +- qrenderdoc/Windows/ShaderViewer.cpp | 2 +- qrenderdoc/Windows/ShaderViewer.h | 2 +- qrenderdoc/Windows/TextureViewer.cpp | 6 +- qrenderdoc/Windows/TextureViewer.h | 2 +- qrenderdoc/Windows/TimelineBar.h | 2 +- renderdoc/api/replay/capture_options.h | 15 +- renderdoc/api/replay/d3d11_pipestate.h | 2 +- renderdoc/api/replay/d3d12_pipestate.h | 2 +- renderdoc/api/replay/data_types.h | 21 +- renderdoc/api/replay/gl_pipestate.h | 2 +- renderdoc/api/replay/pipestate.h | 63 +-- renderdoc/api/replay/pipestate.inl | 20 +- renderdoc/api/replay/renderdoc_replay.h | 232 ++++---- renderdoc/api/replay/replay_enums.h | 29 +- renderdoc/api/replay/shader_types.h | 17 +- renderdoc/api/replay/structured_data.h | 171 +++++- renderdoc/api/replay/vk_pipestate.h | 2 +- renderdoc/core/remote_server.h | 10 +- renderdoc/replay/capture_file.cpp | 20 +- 33 files changed, 1178 insertions(+), 592 deletions(-) create mode 100644 docs/verify-docstrings.py diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index 7d9b2e258..c15164d9d 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -151,6 +151,7 @@ jobs: run: | cd docs make html SPHINXOPTS=-W + python3 ./docs/verify-docstrings.py linux: name: Linux needs: [commit-msg, clang-format] diff --git a/docs/verify-docstrings.py b/docs/verify-docstrings.py new file mode 100644 index 000000000..cd10c7ad0 --- /dev/null +++ b/docs/verify-docstrings.py @@ -0,0 +1,309 @@ +#!/usr/bin/env python3 +# -*- coding: utf-8 -*- +# + +import sys +import re +import os +import glob +import argparse +from enum import EnumMeta +from typing import List + +import struct + +os.chdir(os.path.realpath(os.path.dirname(__file__))) + +# path to module libraries for windows +if struct.calcsize("P") == 8: + binpath = '../x64/' +else: + binpath = '../Win32/' + +# Prioritise release over development builds +sys.path.insert(0, os.path.abspath(binpath + 'Development/pymodules')) +sys.path.insert(0, os.path.abspath(binpath + 'Release/pymodules')) + +# Add the build paths to PATH so renderdoc.dll can be located +os.environ["PATH"] = os.path.abspath(binpath + 'Development/') + os.pathsep + os.environ["PATH"] +os.environ["PATH"] = os.path.abspath(binpath + 'Release/') + os.pathsep + os.environ["PATH"] + +# path to module libraries for linux +sys.path.insert(0, os.path.abspath('../build/lib')) + +import renderdoc as rd +import qrenderdoc as qrd + +parser = argparse.ArgumentParser() +parser.add_argument('-p', '--path', help="Add a path to interface files to search (can be used multiple times)", action='append') +parser.add_argument('-d', '--dump-combined', help="Set a path to dump the combined header that's being searched through", type=str) +parser.add_argument('--debug-mismatches', help="Set a path to a folder, each mismatch creates a file in here with the failure", type=str) +parser.add_argument('-v', '--verbose', + help="Run verbosely", action="store_true") +args = parser.parse_args() + +paths = ['../renderdoc/api/replay', '../qrenderdoc/Code/Interface'] +if args.path is not None: + paths += args.path + +if args.verbose: + print("Searching for interface files in: {}".format(paths)) + +headers = '' + +for path in paths: + for f in glob.glob(os.path.join(os.path.abspath(path), '**', '*.h'), recursive=True): + if args.verbose: + print("Adding interface file {}".format(f)) + with open(f, 'r') as file: + headers += file.read() + +if args.dump_combined is not None: + with open(args.dump_combined, 'w') as file: + file.write(headers) + +if args.debug_mismatches is not None and os.path.isdir(args.debug_mismatches): + for f in glob.glob(os.path.join(os.path.abspath(args.debug_mismatches), '*')): + if args.verbose: + print("Removing {} in debug mismatches folder".format(f)) + os.unlink(f) + +def make_c_type(ret: str, pattern: bool, typelist: List[str]): + orig_type = ret + + # strip namespace + if ret[0:10] == 'renderdoc.': + ret = ret[10:] + + # Handle pipelines that are renamed + if ret == 'D3D11State': + ret = 'D3D11Pipe::State' + elif ret == 'D3D12State': + ret = 'D3D12Pipe::State' + elif ret == 'GLState': + ret = 'GLPipe::State' + elif ret == 'VKState': + ret = 'VKPipe::State' + + if ret in ['bool', 'void']: + pass + elif ret == 'str': + ret = '(const )?rdc(inflexible)?str ?[&*]?' if pattern else 'rdcstr' + elif ret == 'int': + ret = '(u?int[163264]{2}|size)_t' if pattern else 'int' # ambiguous + elif ret == 'float': + ret = 'float|double' if pattern else 'float' + elif ret == 'bytes': + ret = '(const )?bytebuf ?[&*]?' if pattern else 'bytebuf' + elif ret[0:5] == 'List[': + inner = make_c_type(ret[5:-1], pattern, typelist) + ret = '(const )?rdcarray<{}> ?[&*]?'.format(inner) if pattern else 'rdcarray<{}>'.format(inner) + elif ret[0:6] == 'Tuple[': + inners = [make_c_type(i.strip(), pattern, typelist) for i in ret[6:-1].split(',')] + if pattern: + inner = ',\s*'.join(inners) + else: + inner = ', '.join(inners) + ret = '(const )?rdcpair<{}> ?[&*]?'.format(inner) if pattern else 'rdcpair<{}>'.format(inner) + elif pattern: + if ret[-8:] == 'Callback': + ret = '(RENDERDOC_)?{}'.format(ret) + else: + if orig_type not in typelist: + typelist.append(orig_type) + + ret = '(const )?I?{} ?[&*]?'.format(ret) + + return ret + +RTYPE_PATTERN = re.compile(r":rtype: (.*)") +PARAM_PATTERN = re.compile(r":param ([^:]*) ([^: ]*):") + +count = 0 + +def check_function(parent_name, objname, obj, source, global_func, typelist): + global count, args + + if args.verbose: + print("Checking {} function {}.{}".format('global' if global_func else 'member', parent_name, objname)) + + docstring = obj.__doc__ + + params = PARAM_PATTERN.findall(docstring) + + funcargs = ['', ''] + for p in params: + if len(funcargs[0]) > 0: + funcargs[0] += ',\s*' + funcargs[1] += ', ' + funcargs[0] += make_c_type(p[0], True, typelist) + ' ?' + p[1] + "(\s*=[^,]*)?" + funcargs[1] += make_c_type(p[0], False, typelist) + ' ' + p[1] + + result = RTYPE_PATTERN.search(docstring) + if result is not None: + ret = result.group(1) + else: + ret = 'void' + + global_pattern = '' + if global_func: + global_pattern = '(RENDERDOC_CC\s*RENDERDOC_)?' + + pattern = '(?s){} ?{}{}\(\s*{}\)'.format(make_c_type(ret, True, typelist), global_pattern, objname, funcargs[0]) + clean = '{} {}({})'.format(make_c_type(ret, False, typelist), objname, funcargs[1]) + + match = re.search(pattern, source, re.MULTILINE | re.DOTALL) + + pattern2 = None + # global functions returning strings can't return an rdcstr, they have to return const char * + if match is None and ret == 'str': + pattern2 = '(?s)const char \*{}{}\(\s*{}\)'.format(global_pattern, objname, funcargs[0]) + match = re.search(pattern2, source, re.MULTILINE | re.DOTALL) + + if match is None: + count += 1 + print("Error {:3} in {}: {}".format(count, parent_name, clean)) + if args.debug_mismatches is not None and os.path.isdir(args.debug_mismatches): + with open(os.path.join(os.path.abspath(args.debug_mismatches), '{:03}-{}.{}.txt'.format(count, parent_name, objname)), 'w') as file: + file.write("# Failed to find matching declaration for {}.{}\n".format(parent_name, objname)) + file.write("#\n") + file.write("# Matched against {}\n".format(pattern)) + if pattern2 is not None: + file.write("# Matched against {}\n".format(pattern2)) + file.write("#\n") + file.write("#\n") + file.write("\n") + file.write("\n") + file.write(source) + +def check_used_types(objname, module, used_types): + global count + + if args.verbose: + print('Checking {} referenced types: {}'.format(objname, module, used_types)) + + for t in used_types: + type_name = t + parent = module + + while True: + if t in dir(parent): + break + + # Allow some types that are opaque + if parent == rd and t in ['ANativeWindow', 'NSView', 'CALayer', 'wl_display', 'wl_surface', 'HWND', 'xcb_connection_t', 'xcb_window_t', 'Display', 'Drawable']: + break + + if parent == qrd and t in ['QWidget']: + break + + idx = t.find('.') + if idx >= 0: + parent_name = t[0:idx] + if parent_name in dir(parent): + parent = parent.__dict__[parent_name] + elif parent_name == 'renderdoc': + parent = rd + elif parent_name == 'qrenderdoc': + parent = qrd + t = t[idx+1:] + continue + + count += 1 + print("Error {:3} in {}: Unrecognised reference {}".format(count, objname, type_name)) + if type_name in dir(rd): + print(" - Maybe missing namespace to refer to renderdoc.{}?".format(type_name)) + break + +for mod_name in ['renderdoc', 'qrenderdoc']: + mod = sys.modules[mod_name] + if args.verbose: + print("===== Checks for {} =====".format(mod_name)) + for objname in dir(mod): + if re.search('__|SWIG|ResourceId_Null|rdcarray_of|Structured.*List', objname): + continue + + # skip some functions that have special bindings and won't be easily found + if objname in ['CreateRemoteServerConnection', 'DumpObject', 'GetDefaultCaptureOptions', 'GetSupportedDeviceProtocols']: + if args.verbose: + print("Skipping {}".format(objname)) + continue + + obj = mod.__dict__[objname] + + docstring = obj.__doc__ + + if 'INTERNAL:' in docstring: + continue + + qualname = '{}.{}'.format(mod_name, objname) + + if isinstance(obj, EnumMeta): + if args.verbose: + print("Skipping enum {}".format(qualname)) + + # don't check enums + continue + elif isinstance(obj, type): + if args.verbose: + print("Checking class {}".format(qualname)) + + # Grab the source to just this class to search in + source = re.search('(struct|class|union) I?' + objname + '(\n|\s*:[^A-Za-z][\s:a-zA-Z]*\n)\{.*?^}', headers, re.MULTILINE | re.DOTALL) + + namespace = None + + if source is None and objname[0:2] in ['VK', 'GL']: + pipe = objname[0:2] + 'Pipe' + objname = objname[2:] + + namespace = re.search('namespace ' + pipe + '.* namespace ' + pipe, headers, re.MULTILINE | re.DOTALL) + namespace = namespace.group(0) + + if source is None and objname[0:5] in ['D3D11', 'D3D12']: + pipe = objname[0:5] + 'Pipe' + objname = objname[5:] + + namespace = re.search('namespace ' + pipe + '.* namespace ' + pipe, headers, re.MULTILINE | re.DOTALL) + namespace = namespace.group(0) + + if source is None and namespace is not None: + source = re.search('(struct|class|union) I?' + objname + '[^{]*\{.*?^}', headers, re.MULTILINE | re.DOTALL) + + source = source.group(0) + + for member_name in obj.__dict__.keys(): + if '__' in member_name or member_name in ['this', 'thisown']: + continue + + member = obj.__dict__[member_name] + + # Skip some known functions that cannot be easily matched this way + if '{}.{}'.format(objname, member_name) in ['RemoteHost.Connect', + 'CaptureContext.EditShader', + 'ReplayController.DebugThread', + 'ReplayController.GetHistogram', + 'SDObject.AddChild', + 'SDObject.AsInt', + 'SDObject.AsFloat', + 'SDObject.AsString']: + if args.verbose: + print("Skipping {}.{}".format(objname, member_name)) + continue + + if callable(member): + used_types = [] + + check_function(qualname, member_name, member, source, False, used_types) + + check_used_types('{}.{}'.format(qualname, member_name), mod, used_types) + elif callable(obj): + used_types = [] + + # check the function in all headers globally + check_function(mod_name, objname, obj, headers, True, used_types) + + check_used_types(qualname, mod, used_types) + +print("{} mismatches detected".format(count)) +sys.exit(count) diff --git a/qrenderdoc/Code/CaptureContext.cpp b/qrenderdoc/Code/CaptureContext.cpp index a04f77691..002671f15 100644 --- a/qrenderdoc/Code/CaptureContext.cpp +++ b/qrenderdoc/Code/CaptureContext.cpp @@ -2000,11 +2000,6 @@ void CaptureContext::SetResourceCustomName(ResourceId id, const rdcstr &name) RefreshUIStatus({}, true, true); } -int CaptureContext::ResourceNameCacheID() -{ - return m_CustomNameCachedID; -} - #if defined(RENDERDOC_PLATFORM_APPLE) extern "C" void *makeNSViewMetalCompatible(void *handle); #endif @@ -2459,7 +2454,7 @@ IConstantBufferPreviewer *CaptureContext::ViewConstantBuffer(ShaderStage stage, return new ConstantBufferPreviewer(*this, stage, slot, idx, m_MainWindow); } -IPixelHistoryView *CaptureContext::ViewPixelHistory(ResourceId texID, int x, int y, +IPixelHistoryView *CaptureContext::ViewPixelHistory(ResourceId texID, uint32_t x, uint32_t y, const TextureDisplay &display) { return new PixelHistoryView(*this, texID, QPoint(x, y), display, m_MainWindow); diff --git a/qrenderdoc/Code/CaptureContext.h b/qrenderdoc/Code/CaptureContext.h index a13461508..895f58174 100644 --- a/qrenderdoc/Code/CaptureContext.h +++ b/qrenderdoc/Code/CaptureContext.h @@ -170,7 +170,7 @@ public: bool IsAutogeneratedName(ResourceId id) override; bool HasResourceCustomName(ResourceId id) override; void SetResourceCustomName(ResourceId id, const rdcstr &name) override; - int ResourceNameCacheID() override; + int32_t ResourceNameCacheID() override { return m_CustomNameCachedID; } TextureDescription *GetTexture(ResourceId id) override { return m_Textures[id]; } const rdcarray &GetTextures() override { return m_TextureList; } BufferDescription *GetBuffer(ResourceId id) override { return m_Buffers[id]; } @@ -184,7 +184,7 @@ public: WindowingData CreateWindowingData(QWidget *window) override; const rdcarray &DebugMessages() override { return m_DebugMessages; } - int UnreadMessageCount() override { return m_UnreadMessageCount; } + int32_t UnreadMessageCount() override { return m_UnreadMessageCount; } void MarkMessagesRead() override { m_UnreadMessageCount = 0; } void AddMessages(const rdcarray &msgs) override; @@ -264,7 +264,7 @@ public: IConstantBufferPreviewer *ViewConstantBuffer(ShaderStage stage, uint32_t slot, uint32_t idx) override; - IPixelHistoryView *ViewPixelHistory(ResourceId texID, int x, int y, + IPixelHistoryView *ViewPixelHistory(ResourceId texID, uint32_t x, uint32_t y, const TextureDisplay &display) override; QWidget *CreateBuiltinWindow(const rdcstr &objectName) override; diff --git a/qrenderdoc/Code/Interface/Extensions.h b/qrenderdoc/Code/Interface/Extensions.h index ee81d97b9..e827d4e3b 100644 --- a/qrenderdoc/Code/Interface/Extensions.h +++ b/qrenderdoc/Code/Interface/Extensions.h @@ -333,10 +333,18 @@ basic UI building tools for simple data input and display which can be used on a :param CaptureContext context: The current capture context. :param QWidget widget: The widget sending the callback. :param str text: Additional data for the call, such as the current or selected text. + +.. function:: InvokeCallback(context, widget, text) + + Not a member function - the signature for any ``InvokeCallback`` callbacks. + + Callback for invoking onto the UI thread from another thread (in particular the replay thread). + Takes no parameters as the callback is expected to store its own state. )"); struct IMiniQtHelper { typedef std::function WidgetCallback; + typedef std::function InvokeCallback; DOCUMENT(R"(Invoke a callback on the UI thread. All widget accesses must come from the UI thread, so if work has been done on the render thread then this function can be used to asynchronously and @@ -349,9 +357,9 @@ immediately before returning. No parameters are provided to the callback, it is assumed that the callback will maintain its own context as needed. -:param function callback: The callback to invoke on the UI thread. +:param InvokeCallback callback: The callback to invoke on the UI thread. )"); - virtual void InvokeOntoUIThread(std::function callback) = 0; + virtual void InvokeOntoUIThread(InvokeCallback callback) = 0; // top level widgets @@ -369,7 +377,7 @@ added in a vertical layout. This implicitly deletes the widget and all its children, which will no longer be valid even if a handle to them exists. :return: The handle to the newly created widget. -:rtype: ``QWidget`` +:rtype: QWidget )"); virtual QWidget *CreateToplevelWidget(const rdcstr &windowTitle, WidgetCallback closed) = 0; @@ -406,10 +414,10 @@ should only be used for debugging as the name may change even if for the same ty DOCUMENT(R"(Find a child widget of a parent by internal name. -:param QWidget widget: The widget to start the search from. +:param QWidget parent: The widget to start the search from. :param str name: The internal name to search for. :return: The handle to the first widget with a matching name, or ``None`` if no widget is found. -:rtype: ``QWidget`` +:rtype: QWidget )"); virtual QWidget *FindChildByName(QWidget *parent, const rdcstr &name) = 0; @@ -423,7 +431,7 @@ should only be used for debugging as the name may change even if for the same ty :param QWidget widget: The widget to query. :return: The handle to the parent widget with a matching name, or ``None`` if this widget is either not yet parented or is a top-level window. -:rtype: ``QWidget`` +:rtype: QWidget )"); virtual QWidget *GetParent(QWidget *widget) = 0; @@ -434,16 +442,16 @@ layout type widgets. :return: The number of child widgets this widget has. :rtype: int )"); - virtual int GetNumChildren(QWidget *widget) = 0; + virtual int32_t GetNumChildren(QWidget *widget) = 0; DOCUMENT(R"(Return a child widget for a parent. :param QWidget parent: The parent widget to look up. :param int index: The child index to return. :return: The specified child of the parent, or ``None`` if the index is out of bounds. -:rtype: ``QWidget`` +:rtype: QWidget )"); - virtual QWidget *GetChild(QWidget *parent, int index) = 0; + virtual QWidget *GetChild(QWidget *parent, int32_t index) = 0; DOCUMENT(R"(Destroy a widget. Widgets stay alive unless explicitly destroyed here, OR in one other case when they are in a widget hiearchy under a top-level window which the user closes, which can @@ -498,7 +506,7 @@ which typically has some widgets be only large enough for their content and othe 'greedy' evenly divide any remaining free space. :return: The handle to the newly created widget. -:rtype: ``QWidget`` +:rtype: QWidget )"); virtual QWidget *CreateHorizontalContainer() = 0; @@ -511,7 +519,7 @@ which typically has some widgets be only large enough for their content and othe 'greedy' evenly divide any remaining free space. :return: The handle to the newly created widget. -:rtype: ``QWidget`` +:rtype: QWidget )"); virtual QWidget *CreateVerticalContainer() = 0; @@ -524,7 +532,7 @@ which typically has some widgets be only large enough for their content and othe 'greedy' evenly divide any remaining free space. This will not violate the grid constraint though. :return: The handle to the newly created widget. -:rtype: ``QWidget`` +:rtype: QWidget )"); virtual QWidget *CreateGridContainer() = 0; @@ -537,7 +545,7 @@ the same container will be minimally sized. This can be useful for simple layout spacer should consume vertical space. Typically this matches the direction of the layout it is in. :return: The handle to the newly created widget. -:rtype: ``QWidget`` +:rtype: QWidget )"); virtual QWidget *CreateSpacer(bool horizontal) = 0; @@ -559,8 +567,8 @@ happen and the widget will not be added anywhere. :param int rowSpan: How many rows should this child span over. :param int columnSpan: How many columns should this child span over. )"); - virtual void AddGridWidget(QWidget *parent, int row, int column, QWidget *child, int rowSpan, - int columnSpan) = 0; + virtual void AddGridWidget(QWidget *parent, int32_t row, int32_t column, QWidget *child, + int32_t rowSpan, int32_t columnSpan) = 0; DOCUMENT(R"(Adds a child widget to the end of an ordered layout (either horizontal or vertical). If the parent is not an ordered layout nothing will happen and the widget will not be added anywhere. @@ -580,7 +588,7 @@ added anywhere. of children will append the widget :param QWidget child: The child widget to add. )"); - virtual void InsertWidget(QWidget *parent, int index, QWidget *child) = 0; + virtual void InsertWidget(QWidget *parent, int32_t index, QWidget *child) = 0; // widget manipulation @@ -609,7 +617,7 @@ add text next to it. :param bool bold: ``True`` if the font should be bold. :param bool italic: ``True`` if the font should be italic. )"); - virtual void SetWidgetFont(QWidget *widget, const rdcstr &font, int fontSize, bool bold, + virtual void SetWidgetFont(QWidget *widget, const rdcstr &font, int32_t fontSize, bool bold, bool italic) = 0; DOCUMENT(R"(Set whether the widget is enabled or not. This generally only affects interactive @@ -636,7 +644,7 @@ data. in the hierarchy but is not visible and cannot be interacted with in any way. :param QWidget widget: The widget to show or hide. -:param bool enabled: ``True`` if the widget should be made visible (shown). +:param bool visible: ``True`` if the widget should be made visible (shown). )"); virtual void SetWidgetVisible(QWidget *widget, bool visible) = 0; @@ -664,7 +672,7 @@ The widget needs to be added to a parent to become part of a panel or window. :param bool collapsible: ``True`` if the groupbox should have a toggle in its header to allow collapsing its contents down vertically. :return: The handle to the newly created widget. -:rtype: ``QWidget`` +:rtype: QWidget )"); virtual QWidget *CreateGroupBox(bool collapsible) = 0; @@ -672,7 +680,7 @@ The widget needs to be added to a parent to become part of a panel or window. :param WidgetCallback pressed: Callback to be called when the button is pressed. :return: The handle to the newly created widget. -:rtype: ``QWidget`` +:rtype: QWidget )"); virtual QWidget *CreateButton(WidgetCallback pressed) = 0; @@ -682,7 +690,7 @@ The widget needs to be added to a parent to become part of a panel or window. This widget will be blank by default, you can set the text with :meth:`SetWidgetText`. :return: The handle to the newly created widget. -:rtype: ``QWidget`` +:rtype: QWidget )"); virtual QWidget *CreateLabel() = 0; @@ -693,7 +701,7 @@ creating the output as well as call :meth:`SetWidgetReplayOutput` to notify the current output. :return: The handle to the newly created widget. -:rtype: ``QWidget`` +:rtype: QWidget )"); virtual QWidget *CreateOutputRenderingWidget() = 0; @@ -711,9 +719,9 @@ cause the widget to go into an undefined state unless an output is created to re .. note:: This function must be called on the main UI thread. -:param QWidget window: The widget to create windowing data for. +:param QWidget widget: The widget to create windowing data for. :return: The windowing data. -:rtype: ~renderdoc.WindowingData +:rtype: renderdoc.WindowingData )"); virtual WindowingData GetWidgetWindowingData(QWidget *widget) = 0; @@ -727,7 +735,7 @@ 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 +:param renderdoc.ReplayOutput output: The new output to set, or ``None`` to unset any previous output. )"); virtual void SetWidgetReplayOutput(QWidget *widget, IReplayOutput *output) = 0; @@ -752,7 +760,7 @@ created the checkbox is unchecked. :param WidgetCallback changed: Callback to be called when the widget is toggled. :return: The handle to the newly created widget. -:rtype: ``QWidget`` +:rtype: QWidget )"); virtual QWidget *CreateCheckbox(WidgetCallback changed) = 0; @@ -764,7 +772,7 @@ If you want a default radio box to be checked, you should use :meth:`SetWidgetCh :param WidgetCallback changed: Callback to be called when the widget is toggled. :return: The handle to the newly created widget. -:rtype: ``QWidget`` +:rtype: QWidget )"); virtual QWidget *CreateRadiobox(WidgetCallback changed) = 0; @@ -796,9 +804,9 @@ By default the spinbox has minimum and maximum values of 0.0 and 100.0, these ca :param int decimalPlaces: The number of decimal places to display when showing the number. :param float step: The step value to apply in each direction when clicking up or down. :return: The handle to the newly created widget. -:rtype: ``QWidget`` +:rtype: QWidget )"); - virtual QWidget *CreateSpinbox(int decimalPlaces, double step) = 0; + virtual QWidget *CreateSpinbox(int32_t decimalPlaces, double step) = 0; DOCUMENT(R"(Set the minimum and maximum values allowed in the spinbox. If another type of widget is passed nothing will happen. @@ -834,7 +842,7 @@ happen. multi-line text box. :param WidgetCallback changed: Callback to be called when the text in the textbox is changed. :return: The handle to the newly created widget. -:rtype: ``QWidget`` +:rtype: QWidget )"); virtual QWidget *CreateTextBox(bool singleLine, WidgetCallback changed) = 0; @@ -848,7 +856,7 @@ When created there are no pre-defined entries in the drop-down section. This can :param WidgetCallback changed: 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. :return: The handle to the newly created widget. -:rtype: ``QWidget`` +:rtype: QWidget )"); virtual QWidget *CreateComboBox(bool editable, WidgetCallback changed) = 0; @@ -856,7 +864,7 @@ When created there are no pre-defined entries in the drop-down section. This can passed nothing will happen. :param QWidget combo: The combo box. -:param ``list`` of ``str`` options: The new options for the combo box. +:param List[str] options: The new options for the combo box. )"); virtual void SetComboOptions(QWidget *combo, const rdcarray &options) = 0; @@ -893,7 +901,7 @@ struct IExtensionManager DOCUMENT(R"(Retrieve a list of installed extensions. :return: The list of installed extensions. -:rtype: ``list`` of :class:`ExtensionMetadata`. +:rtype: List[ExtensionMetadata] )"); virtual rdcarray GetInstalledExtensions() = 0; @@ -924,11 +932,10 @@ struct IExtensionManager with a child may not receive callbacks at the correct times. :param WindowMenu base: The base menu to add the item to. -:param list submenus: A list of strings containing the submenus to add before the item. The last - string will be the name of the menu item itself. Must contain at least one entry, or two entries - if ``base`` is :data:`WindowMenu.NewMenu`. -:param callback: The function to callback when the menu item is selected. -:type method: :func:`ExtensionCallback` +:param List[str] submenus: A list of strings containing the submenus to add before the item. The + last string will be the name of the menu item itself. Must contain at least one entry, or two + entries if ``base`` is :data:`WindowMenu.NewMenu`. +:param ExtensionCallback callback: The function to callback when the menu item is selected. )"); virtual void RegisterWindowMenu(WindowMenu base, const rdcarray &submenus, ExtensionCallback callback) = 0; @@ -941,10 +948,9 @@ struct IExtensionManager with a child may not receive callbacks at the correct times. :param PanelMenu base: The panel to add the item to. -:param list submenus: A list of strings containing the submenus to add before the item. The last - string will be the name of the menu item itself. Must contain at least one entry. -:param callback: The function to callback when the menu item is selected. -:type method: :func:`ExtensionCallback` +:param List[str] submenus: A list of strings containing the submenus to add before the item. The + last string will be the name of the menu item itself. Must contain at least one entry. +:param ExtensionCallback callback: The function to callback when the menu item is selected. )"); virtual void RegisterPanelMenu(PanelMenu base, const rdcarray &submenus, ExtensionCallback callback) = 0; @@ -957,10 +963,9 @@ struct IExtensionManager with a child may not receive callbacks at the correct times. :param ContextMenu base: The panel to add the item to. -:param list submenus: A list of strings containing the submenus to add before the item. The last - string will be the name of the menu item itself. Must contain at least one entry. -:param callback: The function to callback when the menu item is selected. -:type method: :func:`ExtensionCallback` +:param List[str] submenus: A list of strings containing the submenus to add before the item. The + last string will be the name of the menu item itself. Must contain at least one entry. +:param ExtensionCallback callback: The function to callback when the menu item is selected. )"); virtual void RegisterContextMenu(ContextMenu base, const rdcarray &submenus, ExtensionCallback callback) = 0; @@ -993,7 +998,7 @@ struct IExtensionManager DOCUMENT(R"(Display an error message dialog. :param str text: The text of the dialog itself, required. -:param list options: The buttons to display on the dialog. +:param List[DialogButton] options: The buttons to display on the dialog. :param str title: The dialog title, optional. :return: The button that was clicked on. :rtype: DialogButton diff --git a/qrenderdoc/Code/Interface/PersistantConfig.h b/qrenderdoc/Code/Interface/PersistantConfig.h index a217206cc..0f88c6481 100644 --- a/qrenderdoc/Code/Interface/PersistantConfig.h +++ b/qrenderdoc/Code/Interface/PersistantConfig.h @@ -104,13 +104,13 @@ inline rdcstr ToolExecutable(KnownShaderTool tool) return ""; } -DOCUMENT(R"(Returns the expected default input :class:`ShaderEncoding` that a +DOCUMENT(R"(Returns the expected default input :class:`~renderdoc.ShaderEncoding` that a :class:`KnownShaderTool` expects. This may not be accurate and may be configurable depending on the tool. :param KnownShaderTool tool: The tool to get the input encoding for. :return: The encoding that this tool expects as an input by default. -:rtype: ShaderEncoding +:rtype: renderdoc.ShaderEncoding )"); inline ShaderEncoding ToolInput(KnownShaderTool tool) { @@ -128,13 +128,13 @@ inline ShaderEncoding ToolInput(KnownShaderTool tool) return ShaderEncoding::Unknown; } -DOCUMENT(R"(Returns the expected default output :class:`ShaderEncoding` that a +DOCUMENT(R"(Returns the expected default output :class:`~renderdoc.ShaderEncoding` that a :class:`KnownShaderTool` produces. This may not be accurate and may be configurable depending on the tool. :param KnownShaderTool tool: The tool to get the output encoding for. :return: The encoding that this tool produces as an output by default. -:rtype: ShaderEncoding +:rtype: renderdoc.ShaderEncoding )"); inline ShaderEncoding ToolOutput(KnownShaderTool tool) { @@ -210,21 +210,21 @@ struct ShaderProcessingTool DOCUMENT(R"(Return the default arguments used when invoking this tool :return: The arguments specified for this tool. -:rtype: ``str`` +:rtype: str )"); rdcstr DefaultArguments() const; DOCUMENT(R"(Runs this program to disassemble a given shader reflection. :param QWidget window: A handle to the window to use when showing a progress bar or error messages. -:param ~renderdoc.ShaderReflection shader: The shader to disassemble. +:param renderdoc.ShaderReflection shader: The shader to disassemble. :param str args: arguments to pass to the tool. The default arguments can be obtained using :meth:`DefaultArguments` which can then be customised as desired. Passing an empty string uses the default arguments. :return: The result of running the tool. :rtype: ShaderToolOutput )"); - ShaderToolOutput DisassembleShader(QWidget *window, const ShaderReflection *reflection, + ShaderToolOutput DisassembleShader(QWidget *window, const ShaderReflection *shader, rdcstr args) const; DOCUMENT(R"(Runs this program to disassemble a given shader source. @@ -232,7 +232,7 @@ struct ShaderProcessingTool :param QWidget window: A handle to the window to use when showing a progress bar or error messages. :param str source: The source code, preprocessed into a single file. :param str entryPoint: The name of the entry point in the shader to compile. -:param ~renderdoc.ShaderStage stage: The pipeline stage that this shader represents. +:param renderdoc.ShaderStage stage: The pipeline stage that this shader represents. :param str args: arguments to pass to the tool. The default arguments can be obtained using :meth:`DefaultArguments` which can then be customised as desired. Passing an empty string uses the default arguments. @@ -284,7 +284,7 @@ struct BugReport DOCUMENT(R"(Gets the URL for this report. :return: The URL to the report. -:rtype: ``str`` +:rtype: str )"); rdcstr URL() const; }; @@ -438,8 +438,9 @@ DECLARE_REFLECTION_ENUM(TimeUnit); DOCUMENT(R"(Gets the suffix for a time unit. +:param TimeUnit unit: The unit to get a suffix for. :return: The one or two character suffix. -:rtype: ``str`` +:rtype: str )"); inline rdcstr UnitSuffix(TimeUnit unit) { @@ -461,7 +462,7 @@ not then it's added to the end As the name suggests, this is used for tracking a 'recent file' list. -:param list recentList: A ``list`` of ``str`` that is mutated by the function. +:param List[str] recentList: The list that is mutated by the function. :param str file: The file to add to the list. )"); void AddRecentFile(rdcarray &recentList, const rdcstr &file); @@ -471,7 +472,7 @@ present then the list is not modified. As the name suggests, this is used for tracking a 'recent file' list. -:param list recentList: A ``list`` of ``str`` that is mutated by the function. +:param List[str] recentList: The list that is mutated by the function. :param str file: The file to remove from the list. )"); void RemoveRecentFile(rdcarray &recentList, const rdcstr &file); @@ -502,7 +503,9 @@ For more information about some of these settings that are user-facing see .. data:: RecentCaptureFiles - A ``list`` of ``str`` with the recently opened capture files. + The recently opened capture files. + + :type: List[str] .. data:: LastCapturePath @@ -515,7 +518,9 @@ For more information about some of these settings that are user-facing see .. data:: RecentCaptureSettings - A ``list`` of ``str`` with the recently opened capture settings files. + The recently opened capture settings files. + + :type: List[str] .. data:: TemporaryCaptureDirectory @@ -790,13 +795,14 @@ public: DOCUMENT(R"(Returns a list of all remote hosts. :return: The remote host list -:rtype: ``list`` of ``RemoteHost`` +:rtype: List[RemoteHost] )"); rdcarray GetRemoteHosts(); DOCUMENT(R"(Look up a remote host by hostname. +:param str hostname: The hostname to look up :return: The remote host for the given hostname, or an invalid ``RemoteHost`` if no such exists. -:rtype: ``RemoteHost`` +:rtype: RemoteHost )"); RemoteHost GetRemoteHost(const rdcstr &hostname); @@ -824,7 +830,7 @@ not recommended that you call this function manually. :param str filename: The filename to load from :return: A boolean status if the load was successful. -:rtype: ``bool`` +:rtype: bool )"); bool Load(const rdcstr &filename); @@ -832,7 +838,7 @@ not recommended that you call this function manually. propagated and will not be forgotten in the case of crash or otherwise unexpected exit. :return: A boolean status if the save was successful. -:rtype: ``bool`` +:rtype: bool )"); bool Save(); @@ -853,10 +859,9 @@ loading. It can explicitly save and close before relaunching. Changing the style after the application has started may not properly update everything, so to be sure the new style is applied, the application should be restarted. -:param str name: The name of the setting. :return: ``True`` if the style was set successfully, ``False`` if there was a problem e.g. the value of :data:`UIStyle` was unrecognised or empty. -:rtype: ``bool`` +:rtype: bool )"); bool SetStyle(); diff --git a/qrenderdoc/Code/Interface/QRDInterface.h b/qrenderdoc/Code/Interface/QRDInterface.h index 1753161a6..b2eaafa92 100644 --- a/qrenderdoc/Code/Interface/QRDInterface.h +++ b/qrenderdoc/Code/Interface/QRDInterface.h @@ -116,9 +116,10 @@ struct CaptureSettings rdcstr workingDir; DOCUMENT("The command line to pass when running :data:`executable`."); rdcstr commandLine; - DOCUMENT( - "A ``list`` of :class:`~renderdoc.EnvironmentModification` with environment changes to " - "apply."); + DOCUMENT(R"(The environment changes to apply. + +:type: List[renderdoc.EnvironmentModification] +)"); rdcarray environment; DOCUMENT("The number of queued frames to capture, or 0 if no frames are queued to be captured."); uint32_t numQueuedFrames; @@ -141,9 +142,13 @@ struct IMainWindow { typedef std::function ShortcutCallback; - DOCUMENT( - "Retrieves the QWidget for this :class:`MainWindow` if PySide2 is available, or otherwise a " - "unique opaque pointer that can be passed to RenderDoc functions expecting a QWidget."); + DOCUMENT(R"(Retrieves the PySide2 QWidget for this :class:`MainWindow` if PySide2 is available, or otherwise +returns a unique opaque pointer that can be passed back to any RenderDoc functions expecting a +QWidget. + +:return: Return the widget handle, either a PySide2 handle or an opaque handle. +:rtype: QWidget +)"); virtual QWidget *Widget() = 0; DOCUMENT(R"(Register a callback for a particular key shortcut. @@ -161,6 +166,7 @@ will be invoked, if it exists. :param QWidget widget: A handle to the widget to use as the context for this shortcut, or ``None`` for a global shortcut. Note that if an existing global shortcut exists the new one will not be registered. +:param ShortcutCallback callback: The function to callback when the shortcut is hit. )"); virtual void RegisterShortcut(const rdcstr &shortcut, QWidget *widget, ShortcutCallback callback) = 0; @@ -188,9 +194,13 @@ DECLARE_REFLECTION_STRUCT(IMainWindow); DOCUMENT("The event browser window."); struct IEventBrowser { - DOCUMENT( - "Retrieves the QWidget for this :class:`EventBrowser` if PySide2 is available, or otherwise " - "unique opaque pointer that can be passed to RenderDoc functions expecting a QWidget."); + DOCUMENT(R"(Retrieves the PySide2 QWidget for this :class:`EventBrowser` if PySide2 is available, or otherwise +returns a unique opaque pointer that can be passed back to any RenderDoc functions expecting a +QWidget. + +:return: Return the widget handle, either a PySide2 handle or an opaque handle. +:rtype: QWidget +)"); virtual QWidget *Widget() = 0; DOCUMENT("Updates the duration column if the selected time unit changes."); @@ -206,9 +216,13 @@ DECLARE_REFLECTION_STRUCT(IEventBrowser); DOCUMENT("The API inspector window."); struct IAPIInspector { - DOCUMENT( - "Retrieves the QWidget for this :class:`APIInspector` if PySide2 is available, or otherwise " - "unique opaque pointer that can be passed to RenderDoc functions expecting a QWidget."); + DOCUMENT(R"(Retrieves the PySide2 QWidget for this :class:`APIInspector` if PySide2 is available, or otherwise +returns a unique opaque pointer that can be passed back to any RenderDoc functions expecting a +QWidget. + +:return: Return the widget handle, either a PySide2 handle or an opaque handle. +:rtype: QWidget +)"); virtual QWidget *Widget() = 0; DOCUMENT("Refresh the current API view - useful if callstacks are now available."); @@ -216,7 +230,7 @@ struct IAPIInspector DOCUMENT(R"(Expand the API view to reveal a given parameter and select it. -:param SDObject param: The parameter to reveal and select. +:param renderdoc.SDObject param: The parameter to reveal and select. )"); virtual void RevealParameter(SDObject *param) = 0; @@ -318,15 +332,20 @@ enum class PipelineStage : int DOCUMENT("The pipeline state viewer window."); struct IPipelineStateViewer { - DOCUMENT( - "Retrieves the QWidget for this :class:`PipelineStateViewer` if PySide2 is available, or " - "otherwise unique opaque pointer that can be passed to RenderDoc functions expecting a " - "QWidget."); + DOCUMENT(R"(Retrieves the PySide2 QWidget for this :class:`PipelineStateViewer` if PySide2 is available, or otherwise +returns a unique opaque pointer that can be passed back to any RenderDoc functions expecting a +QWidget. + +:return: Return the widget handle, either a PySide2 handle or an opaque handle. +:rtype: QWidget +)"); virtual QWidget *Widget() = 0; DOCUMENT(R"(Prompt the user to save the binary form of the given shader to disk. -:param ~renderdoc.ShaderReflection shader: The shader reflection data to save. +:param renderdoc.ShaderReflection shader: The shader reflection data to save. +:return: ``True`` if the shader was saved successfully, ``False`` if an error occurred. +:rtype: bool )"); virtual bool SaveShaderFile(const ShaderReflection *shader) = 0; @@ -376,19 +395,22 @@ enum class FollowType : int DOCUMENT("The texture viewer window."); struct ITextureViewer { - DOCUMENT( - "Retrieves the QWidget for this :class:`TextureViewer` if PySide2 is available, or " - "otherwise unique opaque pointer that can be passed to RenderDoc functions expecting a " - "QWidget."); + DOCUMENT(R"(Retrieves the PySide2 QWidget for this :class:`TextureViewer` if PySide2 is available, or otherwise +returns a unique opaque pointer that can be passed back to any RenderDoc functions expecting a +QWidget. + +:return: Return the widget handle, either a PySide2 handle or an opaque handle. +:rtype: QWidget +)"); virtual QWidget *Widget() = 0; DOCUMENT(R"(Open a texture view, optionally raising this window to the foreground. -:param ~renderdoc.ResourceId resourceId: The ID of the texture to view. -:param CompType typeCast: If possible interpret the texture with this type instead of its normal - type. If set to :data:`CompType.Typeless` then no cast is applied, otherwise where allowed the - texture data will be reinterpreted - e.g. from unsigned integers to floats, or to unsigned - normalised values. +:param renderdoc.ResourceId resourceId: The ID of the texture to view. +:param renderdoc.CompType typeCast: If possible interpret the texture with this type instead of its + normal type. If set to :data:`~renderdoc.CompType.Typeless` then no cast is applied, otherwise + where allowed the texture data will be reinterpreted - e.g. from unsigned integers to floats, or + to unsigned normalised values. :param bool focus: ``True`` if the :class:`TextureViewer` should be raised. )"); virtual void ViewTexture(ResourceId resourceId, CompType typeCast, bool focus) = 0; @@ -396,7 +418,7 @@ struct ITextureViewer DOCUMENT(R"(Select the 'following' view and choose which resource slot to follow. :param FollowType followType: The type of followed resource. -:param ShaderStage stage: The shader stage of the shader reflection data to look up. +:param renderdoc.ShaderStage stage: The shader stage of the shader reflection data to look up. :param int index: The index within the given resource list (if applicable) to follow. :param int arrayElement: The index within the given resource array (if applicable) to follow. )"); @@ -406,21 +428,21 @@ struct ITextureViewer DOCUMENT(R"(Return which resource is currently being displayed in the active tab. :return: The ID of the resource being displayed. -:rtype: ~renderdoc.ResourceId +:rtype: renderdoc.ResourceId )"); virtual ResourceId GetCurrentResource() = 0; DOCUMENT(R"(Return which subresource is currently selected for viewing. :return: The subresource currently selected. -:rtype: ~renderdoc.Subresource +:rtype: renderdoc.Subresource )"); virtual Subresource GetSelectedSubresource() = 0; DOCUMENT(R"(Select a particular subresource within the currently selected texture. Any out of bounds parameters will be clamped to the available subresources. -:param Subresource sub: The subresource to select. +:param renderdoc.Subresource sub: The subresource to select. )"); virtual void SetSelectedSubresource(Subresource sub) = 0; @@ -429,33 +451,32 @@ bounds parameters will be clamped to the available subresources. :param int x: The X co-ordinate. :param int y: The Y co-ordinate. )"); - virtual void GotoLocation(int x, int y) = 0; + virtual void GotoLocation(uint32_t x, uint32_t y) = 0; DOCUMENT(R"(Return the currently selected texture overlay. :return: The currently selected texture overlay. -:rtype: ~renderdoc.DebugOverlay +:rtype: renderdoc.DebugOverlay )"); virtual DebugOverlay GetTextureOverlay() = 0; DOCUMENT(R"(Changes the currently selected overlay the given pixel location in the current texture. -:param ~renderdoc.DebugOverlay overlay: The overlay to enable. -:param int y: The Y co-ordinate. +:param renderdoc.DebugOverlay overlay: The overlay to enable. )"); virtual void SetTextureOverlay(DebugOverlay overlay) = 0; DOCUMENT(R"(Return whether or not the texture viewer is currently auto-fitting the zoom level. :return: ``True`` if the zoom level is currently auto-fitting. -:rtype: ``bool`` +:rtype: bool )"); virtual bool IsZoomAutoFit() = 0; DOCUMENT(R"(Return the current zoom level, whether manually set or auto-calculated. :return: The current zoom level, with 100% being represented as 1.0. -:rtype: ``float`` +:rtype: float )"); virtual float GetZoomLevel() = 0; @@ -471,7 +492,7 @@ bounds parameters will be clamped to the available subresources. DOCUMENT(R"(Return the current histogram blackpoint to whitepoint range. :return: The current histogram range. -:rtype: ``tuple`` of two ``float`` +:rtype: Tuple[float,float] )"); virtual rdcpair GetHistogramRange() = 0; @@ -488,7 +509,7 @@ If red is visible ``0x1`` will be set in the returned value, if blue is visible etc. :return: The current bitmask showing channel visibility. -:rtype: ``int`` +:rtype: int )"); virtual uint32_t GetChannelVisibilityBits() = 0; @@ -511,38 +532,42 @@ DECLARE_REFLECTION_STRUCT(ITextureViewer); DOCUMENT("The buffer viewer window, either a raw buffer or the geometry pipeline."); struct IBufferViewer { - DOCUMENT( - "Retrieves the QWidget for this :class:`BufferViewer` if PySide2 is available, or otherwise " - "unique opaque pointer that can be passed to RenderDoc functions expecting a QWidget."); + DOCUMENT(R"(Retrieves the PySide2 QWidget for this :class:`BufferViewer` if PySide2 is available, or otherwise +returns a unique opaque pointer that can be passed back to any RenderDoc functions expecting a +QWidget. + +:return: Return the widget handle, either a PySide2 handle or an opaque handle. +:rtype: QWidget +)"); virtual QWidget *Widget() = 0; DOCUMENT(R"(Scroll to the given row in the given stage's data. :param int row: the row to scroll to. -:param ~renderdoc.MeshDataStage stage: The stage of the geometry pipeline to scroll within. +:param renderdoc.MeshDataStage stage: The stage of the geometry pipeline to scroll within. )"); - virtual void ScrollToRow(int row, MeshDataStage stage = MeshDataStage::VSIn) = 0; + virtual void ScrollToRow(int32_t row, MeshDataStage stage = MeshDataStage::VSIn) = 0; DOCUMENT(R"(Scroll to the given column in the given stage's data. :param int column: the column to scroll to. -:param ~renderdoc.MeshDataStage stage: The stage of the geometry pipeline to scroll within. +:param renderdoc.MeshDataStage stage: The stage of the geometry pipeline to scroll within. )"); - virtual void ScrollToColumn(int column, MeshDataStage stage = MeshDataStage::VSIn) = 0; + virtual void ScrollToColumn(int32_t column, MeshDataStage stage = MeshDataStage::VSIn) = 0; DOCUMENT(R"(For a mesh view, set the current instance. This is ignored when called on a raw buffer view. :param int instance: The instance to select, will be clamped to the range [0, numInstances-1] )"); - virtual void SetCurrentInstance(int instance) = 0; + virtual void SetCurrentInstance(int32_t instance) = 0; DOCUMENT(R"(For a mesh view, set the current multiview view. This is ignored when called on a raw buffer view. :param int view: The view to select, will be clamped to the range [0, numViews-1] )"); - virtual void SetCurrentView(int view) = 0; + virtual void SetCurrentView(int32_t view) = 0; protected: IBufferViewer() = default; @@ -554,28 +579,31 @@ DECLARE_REFLECTION_STRUCT(IBufferViewer); DOCUMENT("The Resource inspector window."); struct IResourceInspector { - DOCUMENT( - "Retrieves the QWidget for this :class:`ResourceInspector` if PySide2 is available, or " - "otherwise " - "unique opaque pointer that can be passed to RenderDoc functions expecting a QWidget."); + DOCUMENT(R"(Retrieves the PySide2 QWidget for this :class:`ResourceInspector` if PySide2 is available, or otherwise +returns a unique opaque pointer that can be passed back to any RenderDoc functions expecting a +QWidget. + +:return: Return the widget handle, either a PySide2 handle or an opaque handle. +:rtype: QWidget +)"); virtual QWidget *Widget() = 0; DOCUMENT(R"(Change the current resource being inspected. -:param ~renderdoc.ResourceId id: The ID of the resource to inspect. +:param renderdoc.ResourceId id: The ID of the resource to inspect. )"); virtual void Inspect(ResourceId id) = 0; DOCUMENT(R"(Return which resource is currently being inspected. :return: The ID of the resource being inspected. -:rtype: ~renderdoc.ResourceId +:rtype: renderdoc.ResourceId )"); virtual ResourceId CurrentResource() = 0; DOCUMENT(R"(Expand the resource initialisation chunks to reveal and select a given parameter. -:param SDObject param: The parameter to reveal and select. +:param renderdoc.SDObject param: The parameter to reveal and select. )"); virtual void RevealParameter(SDObject *param) = 0; @@ -589,16 +617,19 @@ DECLARE_REFLECTION_STRUCT(IResourceInspector); DOCUMENT("The executable capture window."); struct ICaptureDialog { - DOCUMENT( - "Retrieves the QWidget for this :class:`CaptureDialog` if PySide2 is available, or " - "otherwise unique opaque pointer that can be passed to RenderDoc functions expecting a " - "QWidget."); + DOCUMENT(R"(Retrieves the PySide2 QWidget for this :class:`CaptureDialog` if PySide2 is available, or otherwise +returns a unique opaque pointer that can be passed back to any RenderDoc functions expecting a +QWidget. + +:return: Return the widget handle, either a PySide2 handle or an opaque handle. +:rtype: QWidget +)"); virtual QWidget *Widget() = 0; DOCUMENT(R"(Determines if the window is in inject or launch mode. :return: ``True`` if the window is set up for injecting. -:rtype: ``bool`` +:rtype: bool )"); virtual bool IsInjectMode() = 0; DOCUMENT(R"(Switches the window to or from inject mode. @@ -627,7 +658,7 @@ struct ICaptureDialog DOCUMENT(R"(Sets the list of environment modifications to apply when launching. -:param list modifications: The list of :class:`~renderdoc.EnvironmentModification` to apply. +:param List[renderdoc.EnvironmentModification] modifications: The list of modifications to apply. )"); virtual void SetEnvironmentModifications(const rdcarray &modifications) = 0; @@ -675,10 +706,13 @@ DECLARE_REFLECTION_STRUCT(ICaptureDialog); DOCUMENT("The debug warnings and errors window."); struct IDebugMessageView { - DOCUMENT( - "Retrieves the QWidget for this :class:`DebugMessageView` if PySide2 is available, or " - "otherwise unique opaque pointer that can be passed to RenderDoc functions expecting a " - "QWidget."); + DOCUMENT(R"(Retrieves the PySide2 QWidget for this :class:`DebugMessageView` if PySide2 is available, or otherwise +returns a unique opaque pointer that can be passed back to any RenderDoc functions expecting a +QWidget. + +:return: Return the widget handle, either a PySide2 handle or an opaque handle. +:rtype: QWidget +)"); virtual QWidget *Widget() = 0; protected: @@ -691,10 +725,13 @@ DECLARE_REFLECTION_STRUCT(IDebugMessageView); DOCUMENT("The diagnostic log viewing window."); struct IDiagnosticLogView { - DOCUMENT( - "Retrieves the QWidget for this :class:`DiagnosticLogView` if PySide2 is available, or " - "otherwise unique opaque pointer that can be passed to RenderDoc functions expecting a " - "QWidget."); + DOCUMENT(R"(Retrieves the PySide2 QWidget for this :class:`DiagnosticLogView` if PySide2 is available, or otherwise +returns a unique opaque pointer that can be passed back to any RenderDoc functions expecting a +QWidget. + +:return: Return the widget handle, either a PySide2 handle or an opaque handle. +:rtype: QWidget +)"); virtual QWidget *Widget() = 0; protected: @@ -707,10 +744,13 @@ DECLARE_REFLECTION_STRUCT(IDiagnosticLogView); DOCUMENT("The capture comments window."); struct ICommentView { - DOCUMENT( - "Retrieves the QWidget for this :class:`CommentView` if PySide2 is available, or " - "otherwise unique opaque pointer that can be passed to RenderDoc functions expecting a " - "QWidget."); + DOCUMENT(R"(Retrieves the PySide2 QWidget for this :class:`CommentView` if PySide2 is available, or otherwise +returns a unique opaque pointer that can be passed back to any RenderDoc functions expecting a +QWidget. + +:return: Return the widget handle, either a PySide2 handle or an opaque handle. +:rtype: QWidget +)"); virtual QWidget *Widget() = 0; DOCUMENT(R"(Sets the current comments text. @@ -736,10 +776,13 @@ DECLARE_REFLECTION_STRUCT(ICommentView); DOCUMENT("The statistics window."); struct IStatisticsViewer { - DOCUMENT( - "Retrieves the QWidget for this :class:`StatisticsViewer` if PySide2 is available, or " - "otherwise unique opaque pointer that can be passed to RenderDoc functions expecting a " - "QWidget."); + DOCUMENT(R"(Retrieves the PySide2 QWidget for this :class:`StatisticsViewer` if PySide2 is available, or otherwise +returns a unique opaque pointer that can be passed back to any RenderDoc functions expecting a +QWidget. + +:return: Return the widget handle, either a PySide2 handle or an opaque handle. +:rtype: QWidget +)"); virtual QWidget *Widget() = 0; protected: @@ -750,21 +793,25 @@ protected: DOCUMENT("The timeline bar."); struct ITimelineBar { - DOCUMENT( - "Retrieves the QWidget for this :class:`TimelineBar` if PySide2 is available, or otherwise " - "unique opaque pointer that can be passed to RenderDoc functions expecting a QWidget."); + DOCUMENT(R"(Retrieves the PySide2 QWidget for this :class:`TimelineBar` if PySide2 is available, or otherwise +returns a unique opaque pointer that can be passed back to any RenderDoc functions expecting a +QWidget. + +:return: Return the widget handle, either a PySide2 handle or an opaque handle. +:rtype: QWidget +)"); virtual QWidget *Widget() = 0; DOCUMENT(R"(Highlights the frame usage of the specified resource. -:param ~renderdoc.ResourceId id: The ID of the resource to highlight. +:param renderdoc.ResourceId id: The ID of the resource to highlight. )"); virtual void HighlightResourceUsage(ResourceId id) = 0; DOCUMENT(R"(Highlights the modifications in a frame of a given resource. -:param ~renderdoc.ResourceId id: The ID of the resource that is being modified. -:param list history: A list of :class:`~renderdoc.PixelModification` events to display. +:param renderdoc.ResourceId id: The ID of the resource that is being modified. +:param List[renderdoc.PixelModification] history: A list of pixel events to display. )"); virtual void HighlightHistory(ResourceId id, const rdcarray &history) = 0; @@ -778,10 +825,13 @@ DECLARE_REFLECTION_STRUCT(IStatisticsViewer); DOCUMENT("The performance counter view window."); struct IPerformanceCounterViewer { - DOCUMENT( - "Retrieves the QWidget for this :class:`PerformanceCounterViewer` if PySide2 is available, " - "or otherwise unique opaque pointer that can be passed to RenderDoc functions expecting a " - "QWidget."); + DOCUMENT(R"(Retrieves the PySide2 QWidget for this :class:`PerformanceCounterViewer` if PySide2 is available, or otherwise +returns a unique opaque pointer that can be passed back to any RenderDoc functions expecting a +QWidget. + +:return: Return the widget handle, either a PySide2 handle or an opaque handle. +:rtype: QWidget +)"); virtual QWidget *Widget() = 0; protected: @@ -794,9 +844,13 @@ DECLARE_REFLECTION_STRUCT(IPerformanceCounterViewer); DOCUMENT("The interactive python shell."); struct IPythonShell { - DOCUMENT( - "Retrieves the QWidget for this :class:`PythonShell` if PySide2 is available, or otherwise " - "unique opaque pointer that can be passed to RenderDoc functions expecting a QWidget."); + DOCUMENT(R"(Retrieves the PySide2 QWidget for this :class:`PythonShell` if PySide2 is available, or otherwise +returns a unique opaque pointer that can be passed back to any RenderDoc functions expecting a +QWidget. + +:return: Return the widget handle, either a PySide2 handle or an opaque handle. +:rtype: QWidget +)"); virtual QWidget *Widget() = 0; protected: @@ -816,10 +870,10 @@ DOCUMENT(R"(A shader window used for viewing, editing, or debugging. :param CaptureContext context: The current capture context. :param ShaderViewer viewer: The open shader viewer. - :param ResourceId id: The id of the shader being replaced. - :param ShaderStage stage: The shader stage of the shader being replaced. - :param ShaderEncoding encoding: The encoding of the files being passed. - :param ShaderCompileFlags flags: The flags to use during compilation. + :param renderdoc.ResourceId id: The id of the shader being replaced. + :param renderdoc.ShaderStage stage: The shader stage of the shader being replaced. + :param renderdoc.ShaderEncoding encoding: The encoding of the files being passed. + :param renderdoc.ShaderCompileFlags flags: The flags to use during compilation. :param str entryFunc: The name of the entry point. :param bytes source: The byte buffer containing the source - may just be text depending on the encoding. @@ -832,7 +886,7 @@ DOCUMENT(R"(A shader window used for viewing, editing, or debugging. :param CaptureContext context: The current capture context. :param ShaderViewer viewer: The open shader viewer. - :param ResourceId id: The id of the shader being replaced. + :param renderdoc.ResourceId id: The id of the shader being replaced. )"); struct IShaderViewer { @@ -841,15 +895,19 @@ struct IShaderViewer SaveCallback; typedef std::function CloseCallback; - DOCUMENT( - "Retrieves the QWidget for this :class:`ShaderViewer` if PySide2 is available, or otherwise " - "unique opaque pointer that can be passed to RenderDoc functions expecting a QWidget."); + DOCUMENT(R"(Retrieves the PySide2 QWidget for this :class:`ShaderViewer` if PySide2 is available, or otherwise +returns a unique opaque pointer that can be passed back to any RenderDoc functions expecting a +QWidget. + +:return: Return the widget handle, either a PySide2 handle or an opaque handle. +:rtype: QWidget +)"); virtual QWidget *Widget() = 0; DOCUMENT(R"(Retrieves the current step in the debugging. :return: The current step. -:rtype: ``int`` +:rtype: int )"); virtual uint32_t CurrentStep() = 0; @@ -864,7 +922,7 @@ struct IShaderViewer :param int instruction: The instruction to toggle breakpoint at. If this is ``-1`` the nearest instruction after the current caret position is used. )"); - virtual void ToggleBreakpoint(int instruction = -1) = 0; + virtual void ToggleBreakpoint(int32_t instruction = -1) = 0; DOCUMENT(R"(Show a list of shader compilation errors or warnings. @@ -888,10 +946,13 @@ DECLARE_REFLECTION_STRUCT(IShaderViewer); DOCUMENT("A constant buffer preview window."); struct IConstantBufferPreviewer { - DOCUMENT( - "Retrieves the QWidget for this :class:`ConstantBufferPreviewer` if PySide2 is available, or " - "otherwise unique opaque pointer that can be passed to RenderDoc functions expecting a " - "QWidget."); + DOCUMENT(R"(Retrieves the PySide2 QWidget for this :class:`ConstantBufferPreviewer` if PySide2 is available, or otherwise +returns a unique opaque pointer that can be passed back to any RenderDoc functions expecting a +QWidget. + +:return: Return the widget handle, either a PySide2 handle or an opaque handle. +:rtype: QWidget +)"); virtual QWidget *Widget() = 0; protected: @@ -904,15 +965,18 @@ DECLARE_REFLECTION_STRUCT(IConstantBufferPreviewer); DOCUMENT("A pixel history window."); struct IPixelHistoryView { - DOCUMENT( - "Retrieves the QWidget for this :class:`PixelHistoryView` if PySide2 is available, or " - "otherwise unique opaque pointer that can be passed to RenderDoc functions expecting a " - "QWidget."); + DOCUMENT(R"(Retrieves the PySide2 QWidget for this :class:`PixelHistoryView` if PySide2 is available, or otherwise +returns a unique opaque pointer that can be passed back to any RenderDoc functions expecting a +QWidget. + +:return: Return the widget handle, either a PySide2 handle or an opaque handle. +:rtype: QWidget +)"); virtual QWidget *Widget() = 0; DOCUMENT(R"(Set the history displayed in this window. -:param list history: A list of :class:`~renderdoc.PixelModification` events to display. +:param List[renderdoc.PixelModification] history: A list of pixel events to display. )"); virtual void SetHistory(const rdcarray &history) = 0; @@ -971,7 +1035,7 @@ in UI side structures. This manager controls and serialises access to the underl Not a member function - the signature for any ``InvokeCallback`` callbacks. - :param ~renderdoc.ReplayController controller: The controller to access. Must not be cached or + :param renderdoc.ReplayController controller: The controller to access. Must not be cached or used after the callback returns. .. function:: DirectoryBrowseCallback(path, entries) @@ -979,7 +1043,7 @@ in UI side structures. This manager controls and serialises access to the underl Not a member function - the signature for any ``DirectoryBrowseCallback`` callbacks. :param str path: The path that was queried for. - :param list entries: The :class:`~renderdoc.PathEntry` entries underneath the path, as relevant. + :param List[renderdoc.PathEntry] entries: The entries underneath the path, as relevant. )"); struct IReplayManager { @@ -997,7 +1061,7 @@ struct IReplayManager :param RemoteHost host: The host to connect to. :return: Whether or not the connection was successful. -:rtype: ~renderdoc.ReplayStatus +:rtype: renderdoc.ReplayStatus )"); virtual ReplayStatus ConnectToRemoteServer(RemoteHost host) = 0; @@ -1023,7 +1087,7 @@ struct IReplayManager DOCUMENT(R"(Retrieves the capture file handle for the currently open file. :return: The file handle active, or ``None`` if no capture is open. -:rtype: ~renderdoc.CaptureAccess +:rtype: renderdoc.CaptureAccess )"); virtual ICaptureAccess *GetCaptureAccess() = 0; @@ -1036,14 +1100,14 @@ This happens either locally, or on the remote server, depending on whether a con directory containing the executable is used. :param str cmdLine: The command line to use when running the executable, it will be processed in a platform specific way to generate arguments. -:param list env: Any :class:`~renderdoc.EnvironmentModification` that should be made when running - the program. +:param List[renderdoc.EnvironmentModification] env: Any environment changes that should be made when + running the program. :param str capturefile: The location to save any captures, if running locally. -:param CaptureOptions opts: The capture options to use when injecting into the program. -:return: The :class:`ExecuteResult` indicating both the status of the operation (success or failure) - and any reason for failure, or else the ident where the new application is listening for target - control if everything succeeded. -:rtype: ExecuteResult +:param renderdoc.CaptureOptions opts: The capture options to use when injecting into the program. +:return: The :class:`~renderdoc.ExecuteResult` indicating both the status of the operation (success + or failure) and any reason for failure, or else the ident where the new application is listening + for target control if everything succeeded. +:rtype: renderdoc.ExecuteResult )"); virtual ExecuteResult ExecuteAndInject(const rdcstr &exe, const rdcstr &workingDir, const rdcstr &cmdLine, @@ -1053,7 +1117,7 @@ This happens either locally, or on the remote server, depending on whether a con DOCUMENT(R"(Retrieve a list of drivers that the current remote server supports. :return: The list of supported replay drivers. -:rtype: ``list`` of ``str``. +:rtype: List[str] )"); virtual rdcarray GetRemoteSupport() = 0; @@ -1064,10 +1128,9 @@ blocking fashion on the current thread. :param bool synchronous: If a capture is open, then ``True`` will use :meth:`BlockInvoke` to call the callback. Otherwise if ``False`` then :meth:`AsyncInvoke` will be used. -:param method: The function to callback on the replay thread. -:type method: :func:`DirectoryBrowseCallback` +:param DirectoryBrowseCallback callback: The function to callback on the replay thread. )"); - virtual void GetHomeFolder(bool synchronous, DirectoryBrowseCallback cb) = 0; + virtual void GetHomeFolder(bool synchronous, DirectoryBrowseCallback callback) = 0; DOCUMENT(R"(Query the remote host for the contents of a path. @@ -1077,16 +1140,16 @@ blocking fashion on the current thread. :param str path: The path to query the contents of. :param bool synchronous: If a capture is open, then ``True`` will use :meth:`BlockInvoke` to call the callback. Otherwise if ``False`` then :meth:`AsyncInvoke` will be used. -:param DirectoryBrowseCallback method: The function to callback on the replay thread. +:param DirectoryBrowseCallback callback: The function to callback on the replay thread. )"); - virtual void ListFolder(const rdcstr &path, bool synchronous, DirectoryBrowseCallback cb) = 0; + virtual void ListFolder(const rdcstr &path, bool synchronous, DirectoryBrowseCallback callback) = 0; DOCUMENT(R"(Copy a capture from the local machine to the remote host. :param str localpath: The path on the local machine to copy from. :param QWidget window: A handle to the window to use when showing a progress bar. :return: The path on the local machine where the file was saved, or empty if something went wrong. -:rtype: ``str`` +:rtype: str )"); virtual rdcstr CopyCaptureToRemote(const rdcstr &localpath, QWidget *window) = 0; @@ -1106,7 +1169,7 @@ This can be used to identify if a command is long-running to display a progress :return: The time in seconds that the current command has been executing for, or 0.0 if no command is executing. -:rtype: ``float`` +:rtype: float )"); virtual float GetCurrentProcessingTime() = 0; @@ -1345,14 +1408,14 @@ data. :param str appname: The name of the application to use as part of the template. :return: The absolute path. -:rtype: ``str`` +:rtype: str )"); virtual rdcstr TempCaptureFilename(const rdcstr &appname) = 0; DOCUMENT(R"(Open a capture file for replay. :param str captureFile: The actual path to the capture file. -:param ReplayOptions opts: The options controlling how the capture should be replayed. +:param renderdoc.ReplayOptions opts: The options controlling how the capture should be replayed. :param str origFilename: The original filename, if the capture was copied remotely for replay. :param bool temporary: ``True`` if this is a temporary capture which should prompt the user for either save or delete on close. @@ -1371,7 +1434,7 @@ time. :param str captureFile: The path to save the capture file to. :return: ``True`` if the save operation was successful. -:rtype: ``bool`` +:rtype: bool )"); virtual bool SaveCaptureTo(const rdcstr &captureFile) = 0; @@ -1387,11 +1450,11 @@ This converts the file to a specified temporary .rdc and loads it, closing any e The capture must be available locally, if it's not this function will fail. -:param CaptureFileFormat fmt: The capture file format to import from. +:param renderdoc.CaptureFileFormat fmt: The capture file format to import from. :param str importfile: The path to import from. :param str rdcfile: The temporary path to save the rdc file to. :return: ``True`` if the import operation was successful and the capture was loaded. -:rtype: ``bool`` +:rtype: bool )"); virtual bool ImportCapture(const CaptureFileFormat &fmt, const rdcstr &importfile, const rdcstr &rdcfile) = 0; @@ -1400,15 +1463,15 @@ The capture must be available locally, if it's not this function will fail. The capture must be available locally, if it's not this function will fail. -:param CaptureFileFormat fmt: The capture file format to export to. +:param renderdoc.CaptureFileFormat fmt: The capture file format to export to. :param str exportfile: The path to export the capture file to. )"); virtual void ExportCapture(const CaptureFileFormat &fmt, const rdcstr &exportfile) = 0; DOCUMENT(R"(Move the current replay to a new event in the capture. -:param list exclude: A list of :class:`CaptureViewer` to exclude from being notified of this, to stop - infinite recursion. +:param List[CaptureViewer] exclude: A list of viewers to exclude from being notified of this change, + to stop infinite recursion. :param int selectedEventId: The selected :data:`eventId `. See :meth:`CaptureViewer.OnSelectedEventChanged` for more information. :param int eventId: The new current :data:`eventId `. See @@ -1425,7 +1488,9 @@ been made. DOCUMENT(R"(Determine if a resource has been replaced. See :meth:`RegisterReplacement`. -:param ResourceId id: The id of the resource to check. +:param renderdoc.ResourceId id: The id of the resource to check. +:return: ``True`` if the resource has been replaced. +:rtype: bool )"); virtual bool IsResourceReplaced(ResourceId id) = 0; @@ -1434,7 +1499,7 @@ change. This should be called at the same time as :meth:`ReplayController.ReplaceResource`. -:param ResourceId id: The id of the resource that has been replaced. +:param renderdoc.ResourceId id: The id of the resource that has been replaced. )"); virtual void RegisterReplacement(ResourceId id) = 0; @@ -1445,7 +1510,7 @@ This should be called at the same time as :meth:`ReplayController.RemoveReplacem See :meth:`ReplaceResource`. -:param ResourceId id: The id of the original resource that was previously replaced. +:param renderdoc.ResourceId id: The id of the original resource that was previously replaced. )"); virtual void UnregisterReplacement(ResourceId id) = 0; @@ -1480,14 +1545,14 @@ See :meth:`ReplaceResource`. DOCUMENT(R"(Check whether or not a capture is currently loaded. :return: ``True`` if a capture is loaded. -:rtype: ``bool`` +:rtype: bool )"); virtual bool IsCaptureLoaded() = 0; DOCUMENT(R"(Check whether or not the current capture is stored locally, or on a remote host. :return: ``True`` if a capture is local. -:rtype: ``bool`` +:rtype: bool )"); virtual bool IsCaptureLocal() = 0; @@ -1497,21 +1562,21 @@ cleaned up on close (with a final prompt to save). Once they are save to disk, t temporary and treated like any other capture. :return: ``True`` if a capture is temporary. -:rtype: ``bool`` +:rtype: bool )"); virtual bool IsCaptureTemporary() = 0; DOCUMENT(R"(Check whether or not a capture is currently loading in-progress. :return: ``True`` if a capture is currently loading. -:rtype: ``bool`` +:rtype: bool )"); virtual bool IsCaptureLoading() = 0; DOCUMENT(R"(Retrieve the filename for the currently loaded capture. :return: The filename of the current capture. -:rtype: ``str`` +:rtype: str )"); virtual rdcstr GetCaptureFilename() = 0; @@ -1526,14 +1591,14 @@ the UI which aren't reflected in the capture file on disk. DOCUMENT(R"(Retrieve the :class:`~renderdoc.FrameDescription` for the currently loaded capture. :return: The frame information. -:rtype: ~renderdoc.FrameDescription +:rtype: renderdoc.FrameDescription )"); virtual const FrameDescription &FrameInfo() = 0; DOCUMENT(R"(Retrieve the :class:`~renderdoc.APIProperties` for the currently loaded capture. :return: The API properties. -:rtype: ~renderdoc.APIProperties +:rtype: renderdoc.APIProperties )"); virtual const APIProperties &APIProps() = 0; @@ -1542,7 +1607,7 @@ building target shaders for the currently loaded capture. See :meth:`~renderdoc.ReplayController.BuildTargetShader`. :return: The available encodings. -:rtype: ``list`` of :class:`~renderdoc.ShaderEncoding` +:rtype: List[renderdoc.ShaderEncoding] )"); virtual rdcarray TargetShaderEncodings() = 0; @@ -1551,7 +1616,7 @@ building custom shaders for the currently loaded capture. See :meth:`~renderdoc.ReplayController.BuildCustomShader`. :return: The available encodings. -:rtype: ``list`` of :class:`~renderdoc.ShaderEncoding` +:rtype: List[renderdoc.ShaderEncoding] )"); virtual rdcarray CustomShaderEncodings() = 0; @@ -1561,14 +1626,14 @@ In most cases, prefer using :meth:`CurEvent`. See :meth:`CaptureViewer.OnSelecte information for how this differs. :return: The current selected event. -:rtype: ``int`` +:rtype: int )"); virtual uint32_t CurSelectedEvent() = 0; DOCUMENT(R"(Retrieve the current :data:`eventId `. :return: The current event. -:rtype: ``int`` +:rtype: int )"); virtual uint32_t CurEvent() = 0; @@ -1578,50 +1643,50 @@ In most cases, prefer using :meth:`CurDrawcall`. See :meth:`CaptureViewer.OnSele more information for how this differs. :return: The currently selected drawcall. -:rtype: ~renderdoc.DrawcallDescription +:rtype: renderdoc.DrawcallDescription )"); virtual const DrawcallDescription *CurSelectedDrawcall() = 0; DOCUMENT(R"(Retrieve the current drawcall. :return: The current drawcall, or ``None`` if no drawcall is selected. -:rtype: ~renderdoc.DrawcallDescription +:rtype: renderdoc.DrawcallDescription )"); virtual const DrawcallDescription *CurDrawcall() = 0; DOCUMENT(R"(Retrieve the first drawcall in the capture. :return: The first drawcall. -:rtype: ~renderdoc.DrawcallDescription +:rtype: renderdoc.DrawcallDescription )"); virtual const DrawcallDescription *GetFirstDrawcall() = 0; DOCUMENT(R"(Retrieve the last drawcall in the capture. :return: The last drawcall. -:rtype: ~renderdoc.DrawcallDescription +:rtype: renderdoc.DrawcallDescription )"); virtual const DrawcallDescription *GetLastDrawcall() = 0; DOCUMENT(R"(Retrieve the root list of drawcalls in the current capture. :return: The root drawcalls. -:rtype: ``list`` of :class:`~renderdoc.DrawcallDescription` +:rtype: List[renderdoc.DrawcallDescription] )"); virtual const rdcarray &CurDrawcalls() = 0; DOCUMENT(R"(Retrieve the information about a particular resource. -:param ~renderdoc.ResourceId id: The ID of the resource to query about. +: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: renderdoc.ResourceDescription )"); virtual ResourceDescription *GetResource(ResourceId id) = 0; DOCUMENT(R"(Retrieve the list of resources in the current capture. :return: The list of resources. -:rtype: ``list`` of :class:`~renderdoc.ResourceDescription` +:rtype: List[renderdoc.ResourceDescription] )"); virtual const rdcarray &GetResources() = 0; @@ -1632,16 +1697,18 @@ This will first check to see if a custom name has been set for the resource, and in the capture, either a name set via API-specific debug methods, or an auto-generated name based on the resource type. +:param renderdoc.ResourceId id: The ID of the resource to query. :return: The current name of the resource. -:rtype: ``str`` +:rtype: str )"); virtual rdcstr GetResourceName(ResourceId id) = 0; DOCUMENT(R"(Returns the same name as :meth:`GetResourceName` but without any added suffix, e.g. to indicate the resource's status such as (Edited). +:param renderdoc.ResourceId id: The ID of the resource to query. :return: The unsuffixed resource name. -:rtype: ``str`` +:rtype: str )"); virtual rdcstr GetResourceNameUnsuffixed(ResourceId id) = 0; @@ -1651,8 +1718,9 @@ during capture time or with :meth:`SetResourceCustomName`. If not, the name is just auto-generated based on the ID and resource type, so depending on circumstance it may be preferable to omit the name. +:param renderdoc.ResourceId id: The ID of the resource to query. :return: Whether the name for the resource has just been auto-generated. -:rtype: ``bool`` +:rtype: bool )"); virtual bool IsAutogeneratedName(ResourceId id) = 0; @@ -1663,8 +1731,9 @@ generated just from the ID, or if it has been set to some human readable name. T only check if a name has been set in the UI itself, a resource could still have a custom name that was set programmatically during capture time. +:param renderdoc.ResourceId id: The ID of the resource to query. :return: Whether the name for the resource has been customised with :meth:`SetResourceCustomName`. -:rtype: ``bool`` +:rtype: bool )"); virtual bool HasResourceCustomName(ResourceId id) = 0; @@ -1677,7 +1746,7 @@ To remove a custom name that has been set previously, specify the empty string a custom name will be removed, and instead :meth:`GetResourceName` will fall back to returning any name fetched from the capture. -:param ~renderdoc.ResourceId id: The ID of the resource to name. +:param renderdoc.ResourceId id: The ID of the resource to name. :param str name: The name to provide, or an empty string to remove any previous custom name. )"); virtual void SetResourceCustomName(ResourceId id, const rdcstr &name) = 0; @@ -1692,47 +1761,47 @@ The index starts at 1, so initialising an internal cache to 0 will cause the fir considered out of date :return: An incrementing index that can be used as a quick check if any names have changed. -:rtype: ``int`` +:rtype: int )"); - virtual int ResourceNameCacheID() = 0; + virtual int32_t ResourceNameCacheID() = 0; DOCUMENT(R"(Retrieve the information about a particular texture. -:param ~renderdoc.ResourceId id: The ID of the texture to query about. +: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: renderdoc.TextureDescription )"); virtual TextureDescription *GetTexture(ResourceId id) = 0; DOCUMENT(R"(Retrieve the list of textures in the current capture. :return: The list of textures. -:rtype: ``list`` of :class:`~renderdoc.TextureDescription` +:rtype: List[renderdoc.TextureDescription] )"); virtual const rdcarray &GetTextures() = 0; DOCUMENT(R"(Retrieve the information about a particular buffer. -:param ~renderdoc.ResourceId id: The ID of the buffer to query about. +: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: renderdoc.BufferDescription )"); virtual BufferDescription *GetBuffer(ResourceId id) = 0; DOCUMENT(R"(Retrieve the list of buffers in the current capture. :return: The list of buffers. -:rtype: ``list`` of :class:`~renderdoc.BufferDescription` +:rtype: List[renderdoc.BufferDescription] )"); virtual const rdcarray &GetBuffers() = 0; DOCUMENT(R"(Retrieve the information about a drawcall at a given :data:`eventId `. -:param int id: The :data:`eventId ` to query for. +:param int eventId: The :data:`eventId ` to query for. :return: The information about the drawcall, or ``None`` if the :data:`eventId ` doesn't correspond to a drawcall. -:rtype: ~renderdoc.BufferDescription +:rtype: renderdoc.DrawcallDescription )"); virtual const DrawcallDescription *GetDrawcall(uint32_t eventId) = 0; @@ -1747,7 +1816,7 @@ again, any previous connection will be closed. :param str filename: The filename of the extracted temporary RGP capture on disk. :return: Whether RGP launched successfully. -:rtype: ``bool`` +:rtype: bool )"); virtual bool OpenRGPProfile(const rdcstr &filename) = 0; @@ -1770,14 +1839,14 @@ called. DOCUMENT(R"(Retrieve the :class:`~renderdoc.SDFile` for the currently open capture. :return: The structured file. -:rtype: ~renderdoc.SDFile +:rtype: renderdoc.SDFile )"); virtual const SDFile &GetStructuredFile() = 0; DOCUMENT(R"(Retrieve the current windowing system in use. :return: The active windowing system. -:rtype: ~renderdoc.WindowingSystem +:rtype: renderdoc.WindowingSystem )"); virtual WindowingSystem CurWindowingSystem() = 0; @@ -1789,7 +1858,7 @@ called. :param QWidget window: The window to create windowing data for. :return: The windowing data. -:rtype: ~renderdoc.WindowingData +:rtype: renderdoc.WindowingData )"); virtual WindowingData CreateWindowingData(QWidget *window) = 0; @@ -1797,23 +1866,23 @@ called. as well as messages generated during replay and analysis. :return: The debug messages generated to date. -:rtype: ``list`` of :class:`~renderdoc.DebugMessage` +:rtype: List[renderdoc.DebugMessage] )"); virtual const rdcarray &DebugMessages() = 0; DOCUMENT(R"(Retrieve how many messages in :meth:`DebugMessages` are currently unread. :return: The number of unread messages. -:rtype: ``int`` +:rtype: int )"); - virtual int UnreadMessageCount() = 0; + virtual int32_t UnreadMessageCount() = 0; DOCUMENT("Mark all messages as read, resets :meth:`UnreadMessageCount` to 0."); virtual void MarkMessagesRead() = 0; DOCUMENT(R"(Add messages into the list returned by :meth:`DebugMessages`. Initially set to unread. -:param list msgs: A list of :class:`~renderdoc.DebugMessage` to add. +:param List[renderdoc.DebugMessage] msgs: A list of debug messages to add. )"); virtual void AddMessages(const rdcarray &msgs) = 0; @@ -1826,7 +1895,7 @@ Examples of fields are: :param str key: The name of the notes field to retrieve. :return: The contents, or an empty string if the field doesn't exist. -:rtype: ``str`` +:rtype: str )"); virtual rdcstr GetNotes(const rdcstr &key) = 0; @@ -1846,7 +1915,7 @@ The list of bookmarks is not necessarily sorted by eventId. Thus, bookmark 1 is until it is removed, the indices do not shift as new bookmarks are added or removed. :return: The currently set bookmarks. -:rtype: ``list`` of :class:`EventBookmark` +:rtype: List[EventBookmark] )"); virtual rdcarray GetBookmarks() = 0; @@ -1877,7 +1946,7 @@ If no bookmark exists, this function will do nothing. DOCUMENT(R"(Retrieve the current singleton :class:`EventBrowser`. :return: The current window, which is created (but not shown) it there wasn't one open. -:rtype: ~qrenderdoc.EventBrowser +:rtype: EventBrowser )"); virtual IEventBrowser *GetEventBrowser() = 0; @@ -1891,7 +1960,7 @@ If no bookmark exists, this function will do nothing. DOCUMENT(R"(Retrieve the current singleton :class:`TextureViewer`. :return: The current window, which is created (but not shown) it there wasn't one open. -:rtype: ~qrenderdoc.TextureViewer +:rtype: TextureViewer )"); virtual ITextureViewer *GetTextureViewer() = 0; @@ -1905,7 +1974,7 @@ If no bookmark exists, this function will do nothing. DOCUMENT(R"(Retrieve the current singleton :class:`PipelineStateViewer`. :return: The current window, which is created (but not shown) it there wasn't one open. -:rtype: ~qrenderdoc.PipelineStateViewer +:rtype: PipelineStateViewer )"); virtual IPipelineStateViewer *GetPipelineViewer() = 0; @@ -1926,7 +1995,7 @@ If no bookmark exists, this function will do nothing. DOCUMENT(R"(Retrieve the current singleton :class:`LogView`. :return: The current window, which is created (but not shown) it there wasn't one open. -:rtype: LogView +:rtype: DiagnosticLogView )"); virtual IDiagnosticLogView *GetDiagnosticLogView() = 0; @@ -1975,98 +2044,98 @@ If no bookmark exists, this function will do nothing. DOCUMENT(R"(Check if there is a current :class:`EventBrowser` open. :return: ``True`` if there is a window open. -:rtype: ``bool`` +:rtype: bool )"); virtual bool HasEventBrowser() = 0; DOCUMENT(R"(Check if there is a current :class:`APIInspector` open. :return: ``True`` if there is a window open. -:rtype: ``bool`` +:rtype: bool )"); virtual bool HasAPIInspector() = 0; DOCUMENT(R"(Check if there is a current :class:`TextureViewer` open. :return: ``True`` if there is a window open. -:rtype: ``bool`` +:rtype: bool )"); virtual bool HasTextureViewer() = 0; DOCUMENT(R"(Check if there is a current :class:`PipelineStateViewer` open. :return: ``True`` if there is a window open. -:rtype: ``bool`` +:rtype: bool )"); virtual bool HasPipelineViewer() = 0; DOCUMENT(R"(Check if there is a current mesh previewing :class:`BufferViewer` open. :return: ``True`` if there is a window open. -:rtype: ``bool`` +:rtype: bool )"); virtual bool HasMeshPreview() = 0; DOCUMENT(R"(Check if there is a current :class:`CaptureDialog` open. :return: ``True`` if there is a window open. -:rtype: ``bool`` +:rtype: bool )"); virtual bool HasCaptureDialog() = 0; DOCUMENT(R"(Check if there is a current :class:`DebugMessageView` open. :return: ``True`` if there is a window open. -:rtype: ``bool`` +:rtype: bool )"); virtual bool HasDebugMessageView() = 0; DOCUMENT(R"(Check if there is a current :class:`DiagnosticLogView` open. :return: ``True`` if there is a window open. -:rtype: ``bool`` +:rtype: bool )"); virtual bool HasDiagnosticLogView() = 0; DOCUMENT(R"(Check if there is a current :class:`CommentView` open. :return: ``True`` if there is a window open. -:rtype: ``bool`` +:rtype: bool )"); virtual bool HasCommentView() = 0; DOCUMENT(R"(Check if there is a current :class:`PerformanceCounterViewer` open. :return: ``True`` if there is a window open. -:rtype: ``bool`` +:rtype: bool )"); virtual bool HasPerformanceCounterViewer() = 0; DOCUMENT(R"(Check if there is a current :class:`StatisticsViewer` open. :return: ``True`` if there is a window open. -:rtype: ``bool`` +:rtype: bool )"); virtual bool HasStatisticsViewer() = 0; DOCUMENT(R"(Check if there is a current :class:`TimelineBar` open. :return: ``True`` if there is a window open. -:rtype: ``bool`` +:rtype: bool )"); virtual bool HasTimelineBar() = 0; DOCUMENT(R"(Check if there is a current :class:`PythonShell` open. :return: ``True`` if there is a window open. -:rtype: ``bool`` +:rtype: bool )"); virtual bool HasPythonShell() = 0; DOCUMENT(R"(Check if there is a current :class:`ResourceInspector` open. :return: ``True`` if there is a window open. -:rtype: ``bool`` +:rtype: bool )"); virtual bool HasResourceInspector() = 0; @@ -2110,14 +2179,14 @@ place if needed. DOCUMENT(R"(Show a new :class:`ShaderViewer` window, showing an editable view of a given shader. -:param ~renderdoc.ResourceId id: The shader object, if applicable, that's being edited. If this edit +:param renderdoc.ResourceId id: The shader object, if applicable, that's being edited. If this edit corresponds to no shader object (such as if it's a custom shader) this can be a null ID. -:param ~renderdoc.ShaderStage stage: The shader stage for this shader. +:param renderdoc.ShaderStage stage: The shader stage for this shader. :param str entryPoint: The entry point to be used when compiling the edited shader. -:param list files: The files stored in a ``list`` with 2-tuples of ``str``. The first element being - the filename and the second being the file contents. -:param ~renderdoc.ShaderEncoding shaderEncoding: The encoding of the input files. -:param ~renderdoc.ShaderCompileFlags flags: The flags originally used to compile the shader. +:param List[Tuple[str,str]] files: The source files, with each tuple being a pair of the filename + and the file contents. +:param renderdoc.ShaderEncoding shaderEncoding: The encoding of the input files. +:param renderdoc.ShaderCompileFlags flags: The flags originally used to compile the shader. :param ShaderViewer.SaveCallback saveCallback: The callback function to call when a save/update is triggered. :param ShaderViewer.CloseCallback closeCallback: The callback function to call when the shader @@ -2134,11 +2203,11 @@ place if needed. DOCUMENT(R"(Show a new :class:`ShaderViewer` window, showing a read-only view of a debug trace through the execution of a given shader. -:param ~renderdoc.ShaderBindpointMapping bind: The bindpoint mapping for the shader to view. -:param ~renderdoc.ShaderReflection shader: The reflection data for the shader to view. -:param ~renderdoc.ResourceId pipeline: The pipeline state object, if applicable, that this shader is +:param renderdoc.ShaderBindpointMapping bind: The bindpoint mapping for the shader to view. +:param renderdoc.ShaderReflection shader: The reflection data for the shader to view. +:param renderdoc.ResourceId pipeline: The pipeline state object, if applicable, that this shader is bound to. -:param ~renderdoc.ShaderDebugTrace trace: The execution trace of the debugged shader. +:param renderdoc.ShaderDebugTrace trace: The execution trace of the debugged shader. :param str debugContext: A human-readable context string describing which invocation of this shader was debugged. For example 'Pixel 12,34 at eventId 678'. :return: The new :class:`ShaderViewer` window opened, but not shown. @@ -2150,8 +2219,8 @@ through the execution of a given shader. DOCUMENT(R"(Show a new :class:`ShaderViewer` window, showing a read-only view of a given shader. -:param ~renderdoc.ShaderReflection shader: The reflection data for the shader to view. -:param ~renderdoc.ResourceId pipeline: The pipeline state object, if applicable, that this shader is +:param renderdoc.ShaderReflection shader: The reflection data for the shader to view. +:param renderdoc.ResourceId pipeline: The pipeline state object, if applicable, that this shader is bound to. :return: The new :class:`ShaderViewer` window opened, but not shown. :rtype: ShaderViewer @@ -2162,7 +2231,7 @@ through the execution of a given shader. :param int byteOffset: The offset in bytes to the start of the buffer data to show. :param int byteSize: The number of bytes in the buffer to show. -:param ~renderdoc.ResourceId id: The ID of the buffer to fetch data from. +:param renderdoc.ResourceId id: The ID of the buffer to fetch data from. :param str format: Optionally a HLSL/GLSL style formatting string. :return: The new :class:`BufferViewer` window opened, but not shown. :rtype: BufferViewer @@ -2173,8 +2242,8 @@ through the execution of a given shader. DOCUMENT(R"(Show a new :class:`BufferViewer` window, showing a read-only view of a texture's raw bytes. -:param ~renderdoc.ResourceId id: The ID of the texture itself. -:param Subresource sub: The subresource within this texture to use. +:param renderdoc.ResourceId id: The ID of the texture itself. +:param renderdoc.Subresource sub: The subresource within this texture to use. :param str format: Optionally a HLSL/GLSL style formatting string. :return: The new :class:`BufferViewer` window opened, but not shown. :rtype: BufferViewer @@ -2185,7 +2254,7 @@ bytes. DOCUMENT(R"(Show a new :class:`ConstantBufferPreviewer` window, showing a read-only view of a the variables in a constant buffer with their values. -:param ~renderdoc.ShaderStage stage: The stage that the constant buffer is bound to. +:param renderdoc.ShaderStage stage: The stage that the constant buffer is bound to. :param int slot: The index in the shader's constant buffer list to look up. :param int idx: For APIs that support arrayed resource binds, the index in the constant buffer array. @@ -2198,15 +2267,15 @@ variables in a constant buffer with their values. DOCUMENT(R"(Show a new :class:`PixelHistoryView` window, showing the results from a pixel history operation. -:param ~renderdoc.ResourceId id: The ID of the texture to show the history of. -:param int X: The x co-ordinate of the pixel to search for. -:param int Y: The y co-ordinate of the pixel to search for. -:param ~renderdoc.TextureDisplay display: The texture display configuration to use when looking up +:param renderdoc.ResourceId id: The ID of the texture to show the history of. +:param int x: The x co-ordinate of the pixel to search for. +:param int y: The y co-ordinate of the pixel to search for. +:param renderdoc.TextureDisplay display: The texture display configuration to use when looking up the history. :return: The new :class:`PixelHistoryView` window opened, but not shown. :rtype: PixelHistoryView )"); - virtual IPixelHistoryView *ViewPixelHistory(ResourceId texID, int x, int y, + virtual IPixelHistoryView *ViewPixelHistory(ResourceId id, uint32_t x, uint32_t y, const TextureDisplay &display) = 0; DOCUMENT(R"(Creates and returns a built-in window. @@ -2216,7 +2285,7 @@ by user code. :param str objectName: The built-in name of a singleton window. :return: The handle to the existing or newly created window of this type. -:rtype: ``QWidget`` +:rtype: QWidget )"); virtual QWidget *CreateBuiltinWindow(const rdcstr &objectName) = 0; @@ -2238,7 +2307,7 @@ currently docked. DOCUMENT(R"(Adds a new window within the docking system. -:param QWidget dockWindow: The new window to add. +:param QWidget newWindow: The new window to add. :param DockReference ref: The location to add the new window, possibly relative to ``refWindow``. :param QWidget refWindow: The window to refer to if the new window is being added relative, or can be ``None`` if the new location is absolute. @@ -2254,7 +2323,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: renderdoc.D3D11State )"); virtual const D3D11Pipe::State *CurD3D11PipelineState() = 0; @@ -2264,7 +2333,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: renderdoc.D3D12State )"); virtual const D3D12Pipe::State *CurD3D12PipelineState() = 0; @@ -2274,7 +2343,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: renderdoc.GLState )"); virtual const GLPipe::State *CurGLPipelineState() = 0; @@ -2284,7 +2353,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: renderdoc.VKState )"); virtual const VKPipe::State *CurVulkanPipelineState() = 0; @@ -2294,7 +2363,7 @@ This pipeline state will always be valid, and allows queries that will work rega capture's API. :return: The current API-agnostic abstracted pipeline state. -:rtype: ~renderdoc.PipeState +:rtype: renderdoc.PipeState )"); virtual const PipeState &CurPipelineState() = 0; diff --git a/qrenderdoc/Code/Interface/RemoteHost.h b/qrenderdoc/Code/Interface/RemoteHost.h index f0bcd0bb7..f783fb3ef 100644 --- a/qrenderdoc/Code/Interface/RemoteHost.h +++ b/qrenderdoc/Code/Interface/RemoteHost.h @@ -59,34 +59,68 @@ public: DOCUMENT( "Ping the host to check current status - if the server is running, connection status, etc."); void CheckStatus(); - DOCUMENT( - "Runs the command specified in :data:`runCommand`. Returns :class:`ReplayStatus` which " - "indicates success or the type of failure."); + + DOCUMENT(R"(Runs the command specified in :data:`runCommand`. Returns +:class:`~renderdoc.ReplayStatus` which indicates success or the type of failure. + +:return: The result from launching the remote server. +:rtype: renderdoc.ReplayStatus +)"); ReplayStatus Launch(); - DOCUMENT("``True`` if a remote server is currently running on this host."); + DOCUMENT(R"( +:return: ``True`` if a remote server is currently running on this host. +:rtype: bool +)"); bool IsServerRunning() const; - DOCUMENT("``True`` if an active connection exists to this remote server."); + + DOCUMENT(R"( +:return: ``True`` if an active connection exists to this remote server. +:rtype: bool +)"); bool IsConnected() const; - DOCUMENT("``True`` if someone else is currently connected to this server."); + + DOCUMENT(R"( +:return: ``True`` if someone else is currently connected to this server. +:rtype: bool +)"); bool IsBusy() const; - DOCUMENT("``True`` if there is a code version mismatch with this server."); + + DOCUMENT(R"( +:return: ``True`` if there is a code version mismatch with this server. +:rtype: bool +)"); bool IsVersionMismatch() const; - DOCUMENT("The hostname of this host."); - const rdcstr &Hostname() const { return m_hostname; } - DOCUMENT("The friendly name for this host, if available (if empty, the Hostname is used)."); + DOCUMENT(R"( +:return: The hostname of this host. +:rtype: str +)"); + rdcstr Hostname() const { return m_hostname; } + DOCUMENT(R"( +:return: The friendly name for this host, if available (if empty, the Hostname is used). +:rtype: str +)"); rdcstr FriendlyName() const; - DOCUMENT("The command to run locally to try to launch the server remotely."); + + DOCUMENT(R"( +:return: The command to run locally to try to launch the server remotely. +:rtype: str +)"); rdcstr RunCommand() const; + DOCUMENT(R"(Sets the run command. See :meth:`RunCommand`. :param str cmd: The new command to set. )"); void SetRunCommand(const rdcstr &cmd); - DOCUMENT("The last folder browsed to on this host, to provide a reasonable default path."); + DOCUMENT(R"( +:return: The last folder browsed to on this host, to provide a reasonable default path. +:rtype: str +)"); rdcstr LastCapturePath() const; + DOCUMENT(R"(Sets the last folder browsed to. See :meth:`LastCapturePath`. :param str path: The new path to set. @@ -97,25 +131,35 @@ public: :return: The status of opening the capture, whether success or failure, and a :class:`RemoteServer` instance if it were successful -:rtype: ``pair`` of ReplayStatus and RemoteServer +:rtype: Tuple[renderdoc.ReplayStatus, renderdoc.RemoteServer] )"); ReplayStatus Connect(IRemoteServer **server); - DOCUMENT( - "The :class:`DeviceProtocolController` for this host, or ``None`` if no protocol is in use"); + DOCUMENT(R"( +:return: The :class:`~renderdoc.DeviceProtocolController` for this host, or ``None`` if no protocol + is in use +:rtype: renderdoc.DeviceProtocolController +)"); IDeviceProtocolController *Protocol() const { return m_protocol; } DOCUMENT(R"( -Returns the name to display for this host in the UI, either :meth:`FriendlyName` if it is valid, or +:return: The name to display for this host in the UI, either :meth:`FriendlyName` if it is valid, or :meth:`Hostname` if not. +:rtype: str )"); rdcstr Name() const { rdcstr friendlyName = FriendlyName(); return !friendlyName.isEmpty() ? friendlyName : m_hostname; } - DOCUMENT("Returns ``True`` if this host represents the special localhost device."); + + DOCUMENT(R"( +:return: Returns ``True`` if this host represents the special localhost device. +:rtype: bool +)"); bool IsLocalhost() const { return m_hostname == "localhost"; } - DOCUMENT("Returns ``True`` if this host represents a valid remote host."); + DOCUMENT(R"(Returns ``True`` if this host represents a valid remote host. +:rtype: bool +)"); bool IsValid() const { return m_data && !m_hostname.isEmpty(); } private: // this is immutable and is used as a key to look up data, it's always valid as RemoteHost objects diff --git a/qrenderdoc/Code/MiniQtHelper.cpp b/qrenderdoc/Code/MiniQtHelper.cpp index 4d84ec44b..490e4bf6e 100644 --- a/qrenderdoc/Code/MiniQtHelper.cpp +++ b/qrenderdoc/Code/MiniQtHelper.cpp @@ -136,7 +136,7 @@ QWidget *MiniQtHelper::GetParent(QWidget *widget) return widget->parentWidget(); } -int MiniQtHelper::GetNumChildren(QWidget *widget) +int32_t MiniQtHelper::GetNumChildren(QWidget *widget) { if(!widget) return 0; @@ -148,7 +148,7 @@ int MiniQtHelper::GetNumChildren(QWidget *widget) return layout->count(); } -QWidget *MiniQtHelper::GetChild(QWidget *parent, int index) +QWidget *MiniQtHelper::GetChild(QWidget *parent, int32_t index) { if(!parent) return NULL; @@ -249,8 +249,8 @@ void MiniQtHelper::ClearContainedWidgets(QWidget *parent) } } -void MiniQtHelper::AddGridWidget(QWidget *parent, int row, int column, QWidget *child, int rowSpan, - int columnSpan) +void MiniQtHelper::AddGridWidget(QWidget *parent, int32_t row, int32_t column, QWidget *child, + int32_t rowSpan, int32_t columnSpan) { if(!parent || !child) return; @@ -282,7 +282,7 @@ void MiniQtHelper::AddWidget(QWidget *parent, QWidget *child) box->addWidget(child); } -void MiniQtHelper::InsertWidget(QWidget *parent, int index, QWidget *child) +void MiniQtHelper::InsertWidget(QWidget *parent, int32_t index, QWidget *child) { if(!parent) return; @@ -384,7 +384,7 @@ rdcstr MiniQtHelper::GetWidgetText(QWidget *widget) return widget->windowTitle(); } -void MiniQtHelper::SetWidgetFont(QWidget *widget, const rdcstr &font, int fontSize, bool bold, +void MiniQtHelper::SetWidgetFont(QWidget *widget, const rdcstr &font, int32_t fontSize, bool bold, bool italic) { if(!widget) @@ -555,7 +555,7 @@ bool MiniQtHelper::IsWidgetChecked(QWidget *checkableWidget) return false; } -QWidget *MiniQtHelper::CreateSpinbox(int decimalPlaces, double step) +QWidget *MiniQtHelper::CreateSpinbox(int32_t decimalPlaces, double step) { RDDoubleSpinBox *ret = new RDDoubleSpinBox(); ret->setSingleStep(step); diff --git a/qrenderdoc/Code/MiniQtHelper.h b/qrenderdoc/Code/MiniQtHelper.h index 948b2f0c1..5c99713c3 100644 --- a/qrenderdoc/Code/MiniQtHelper.h +++ b/qrenderdoc/Code/MiniQtHelper.h @@ -46,8 +46,8 @@ public: rdcstr GetWidgetType(QWidget *widget) override; QWidget *FindChildByName(QWidget *parent, const rdcstr &name) override; QWidget *GetParent(QWidget *widget) override; - int GetNumChildren(QWidget *widget) override; - QWidget *GetChild(QWidget *parent, int index) override; + int32_t GetNumChildren(QWidget *widget) override; + QWidget *GetChild(QWidget *parent, int32_t index) override; void DestroyWidget(QWidget *widget) override; // dialogs @@ -63,17 +63,17 @@ public: QWidget *CreateSpacer(bool horizontal) override; void ClearContainedWidgets(QWidget *parent) override; - void AddGridWidget(QWidget *parent, int row, int column, QWidget *child, int rowSpan, - int columnSpan) override; + void AddGridWidget(QWidget *parent, int32_t row, int32_t column, QWidget *child, int32_t rowSpan, + int32_t columnSpan) override; void AddWidget(QWidget *parent, QWidget *child) override; - void InsertWidget(QWidget *parent, int index, QWidget *child) override; + void InsertWidget(QWidget *parent, int32_t index, QWidget *child) override; // widget manipulation void SetWidgetText(QWidget *widget, const rdcstr &text) override; rdcstr GetWidgetText(QWidget *widget) override; - void SetWidgetFont(QWidget *widget, const rdcstr &font, int fontSize, bool bold, + void SetWidgetFont(QWidget *widget, const rdcstr &font, int32_t fontSize, bool bold, bool italic) override; void SetWidgetEnabled(QWidget *widget, bool enabled) override; @@ -102,7 +102,7 @@ public: void SetWidgetChecked(QWidget *checkableWidget, bool checked) override; bool IsWidgetChecked(QWidget *checkableWidget) override; - QWidget *CreateSpinbox(int decimalPlaces, double step) override; + QWidget *CreateSpinbox(int32_t decimalPlaces, double step) override; void SetSpinboxBounds(QWidget *spinbox, double minVal, double maxVal) override; void SetSpinboxValue(QWidget *spinbox, double value) override; diff --git a/qrenderdoc/Code/pyrenderdoc/renderdoc.i b/qrenderdoc/Code/pyrenderdoc/renderdoc.i index 8606ca2cc..4724b47c9 100644 --- a/qrenderdoc/Code/pyrenderdoc/renderdoc.i +++ b/qrenderdoc/Code/pyrenderdoc/renderdoc.i @@ -268,7 +268,7 @@ TEMPLATE_ARRAY_DECLARE(rdcarray); the built-in repr() function but it iterates over struct members and prints them out, where normally repr() would stop and say something like 'Swig Object of type ...'. -:param Any object: The object to dump +:param Any obj: The object to dump :return: The string representation of the object. :rtype: str )"; @@ -284,6 +284,9 @@ extern "C" PyObject *RENDERDOC_DumpObject(PyObject *obj); %extend SDObject { %feature("docstring") R"(Interprets the object as an integer and returns its value. Invalid if the object is not actually an integer. + +:return: The interpreted integer. +:rtype: int )"; PyObject *AsInt() { @@ -295,11 +298,17 @@ Invalid if the object is not actually an integer. %feature("docstring") R"(Interprets the object as a floating point number and returns its value. Invalid if the object is not actually a floating point number. + +:return: The interpreted float. +:rtype: float )"; PyObject *AsFloat() { return ConvertToPy($self->data.basic.d); } %feature("docstring") R"(Interprets the object as a string and returns its value. Invalid if the object is not actually a string. + +:return: The interpreted string. +:rtype: str )"; PyObject *AsString() { return ConvertToPy($self->data.str); } } diff --git a/qrenderdoc/Windows/BufferViewer.cpp b/qrenderdoc/Windows/BufferViewer.cpp index 7939d4190..17bd5df92 100644 --- a/qrenderdoc/Windows/BufferViewer.cpp +++ b/qrenderdoc/Windows/BufferViewer.cpp @@ -3386,13 +3386,13 @@ void BufferViewer::ScrollToColumn(RDTableView *view, int column) view->verticalScrollBar()->setValue(vs); } -void BufferViewer::SetCurrentInstance(int instance) +void BufferViewer::SetCurrentInstance(int32_t instance) { if(ui->instance->isVisible() && ui->instance->isEnabled()) ui->instance->setValue(instance); } -void BufferViewer::SetCurrentView(int view) +void BufferViewer::SetCurrentView(int32_t view) { if(ui->viewIndex->isVisible() && ui->viewIndex->isEnabled()) ui->viewIndex->setValue(view); @@ -3440,7 +3440,7 @@ void BufferViewer::ViewTexture(ResourceId id, const Subresource &sub, const rdcs processFormat(format); } -void BufferViewer::ScrollToRow(int row, MeshDataStage stage) +void BufferViewer::ScrollToRow(int32_t row, MeshDataStage stage) { ScrollToRow(tableForStage(stage), row); @@ -3451,7 +3451,7 @@ void BufferViewer::ScrollToRow(int row, MeshDataStage stage) ui->rowOffset->setValue(row); } -void BufferViewer::ScrollToColumn(int column, MeshDataStage stage) +void BufferViewer::ScrollToColumn(int32_t column, MeshDataStage stage) { ScrollToColumn(tableForStage(stage), column); diff --git a/qrenderdoc/Windows/BufferViewer.h b/qrenderdoc/Windows/BufferViewer.h index ad289191b..6d015f6b2 100644 --- a/qrenderdoc/Windows/BufferViewer.h +++ b/qrenderdoc/Windows/BufferViewer.h @@ -84,10 +84,10 @@ public: // IBufferViewer QWidget *Widget() override { return this; } - void ScrollToRow(int row, MeshDataStage stage = MeshDataStage::VSIn) override; - void ScrollToColumn(int column, MeshDataStage stage = MeshDataStage::VSIn) override; - void SetCurrentInstance(int instance) override; - void SetCurrentView(int view) override; + void ScrollToRow(int32_t row, MeshDataStage stage = MeshDataStage::VSIn) override; + void ScrollToColumn(int32_t column, MeshDataStage stage = MeshDataStage::VSIn) override; + void SetCurrentInstance(int32_t instance) override; + void SetCurrentView(int32_t view) override; // ICaptureViewer void OnCaptureLoaded() override; diff --git a/qrenderdoc/Windows/PythonShell.cpp b/qrenderdoc/Windows/PythonShell.cpp index e5ae9ce2e..0807650fb 100644 --- a/qrenderdoc/Windows/PythonShell.cpp +++ b/qrenderdoc/Windows/PythonShell.cpp @@ -122,11 +122,11 @@ struct MiniQtInvoker : ObjectForwarder { return InvokeRetFunction(&IMiniQtHelper::GetParent, widget); } - int GetNumChildren(QWidget *widget) + int32_t GetNumChildren(QWidget *widget) { - return InvokeRetFunction(&IMiniQtHelper::GetNumChildren, widget); + return InvokeRetFunction(&IMiniQtHelper::GetNumChildren, widget); } - QWidget *GetChild(QWidget *parent, int index) + QWidget *GetChild(QWidget *parent, int32_t index) { return InvokeRetFunction(&IMiniQtHelper::GetChild, parent, index); } @@ -164,7 +164,8 @@ struct MiniQtInvoker : ObjectForwarder { InvokeVoidFunction(&IMiniQtHelper::ClearContainedWidgets, parent); } - void AddGridWidget(QWidget *parent, int row, int column, QWidget *child, int rowSpan, int columnSpan) + void AddGridWidget(QWidget *parent, int32_t row, int32_t column, QWidget *child, int32_t rowSpan, + int32_t columnSpan) { InvokeVoidFunction(&IMiniQtHelper::AddGridWidget, parent, row, column, child, rowSpan, columnSpan); @@ -173,7 +174,7 @@ struct MiniQtInvoker : ObjectForwarder { InvokeVoidFunction(&IMiniQtHelper::AddWidget, parent, child); } - void InsertWidget(QWidget *parent, int index, QWidget *child) + void InsertWidget(QWidget *parent, int32_t index, QWidget *child) { InvokeVoidFunction(&IMiniQtHelper::InsertWidget, parent, index, child); } @@ -189,7 +190,7 @@ struct MiniQtInvoker : ObjectForwarder return InvokeRetFunction(&IMiniQtHelper::GetWidgetText, widget); } - void SetWidgetFont(QWidget *widget, const rdcstr &font, int fontSize, bool bold, bool italic) + void SetWidgetFont(QWidget *widget, const rdcstr &font, int32_t fontSize, bool bold, bool italic) { InvokeVoidFunction(&IMiniQtHelper::SetWidgetFont, widget, font, fontSize, bold, italic); } @@ -260,7 +261,7 @@ struct MiniQtInvoker : ObjectForwarder return InvokeRetFunction(&IMiniQtHelper::IsWidgetChecked, checkableWidget); } - QWidget *CreateSpinbox(int decimalPlaces, double step) + QWidget *CreateSpinbox(int32_t decimalPlaces, double step) { return InvokeRetFunction(&IMiniQtHelper::CreateSpinbox, decimalPlaces, step); } @@ -450,7 +451,7 @@ struct CaptureContextInvoker : ObjectForwarder { return m_Obj.HasResourceCustomName(id); } - virtual int ResourceNameCacheID() override { return m_Obj.ResourceNameCacheID(); } + virtual int32_t ResourceNameCacheID() override { return m_Obj.ResourceNameCacheID(); } virtual TextureDescription *GetTexture(ResourceId id) override { return m_Obj.GetTexture(id); } virtual const rdcarray &GetTextures() override { return m_Obj.GetTextures(); } virtual BufferDescription *GetBuffer(ResourceId id) override { return m_Obj.GetBuffer(id); } @@ -467,7 +468,7 @@ struct CaptureContextInvoker : ObjectForwarder virtual const SDFile &GetStructuredFile() override { return m_Obj.GetStructuredFile(); } virtual WindowingSystem CurWindowingSystem() override { return m_Obj.CurWindowingSystem(); } virtual const rdcarray &DebugMessages() override { return m_Obj.DebugMessages(); } - virtual int UnreadMessageCount() override { return m_Obj.UnreadMessageCount(); } + virtual int32_t UnreadMessageCount() override { return m_Obj.UnreadMessageCount(); } virtual void MarkMessagesRead() override { return m_Obj.MarkMessagesRead(); } virtual rdcstr GetNotes(const rdcstr &key) override { return m_Obj.GetNotes(key); } virtual rdcarray GetBookmarks() override { return m_Obj.GetBookmarks(); } @@ -775,7 +776,7 @@ struct CaptureContextInvoker : ObjectForwarder stage, slot, idx); } - virtual IPixelHistoryView *ViewPixelHistory(ResourceId texID, int x, int y, + virtual IPixelHistoryView *ViewPixelHistory(ResourceId texID, uint32_t x, uint32_t y, const TextureDisplay &display) override { return InvokeRetFunction(&ICaptureContext::ViewPixelHistory, texID, x, y, diff --git a/qrenderdoc/Windows/ShaderViewer.cpp b/qrenderdoc/Windows/ShaderViewer.cpp index 536675750..b8f693638 100644 --- a/qrenderdoc/Windows/ShaderViewer.cpp +++ b/qrenderdoc/Windows/ShaderViewer.cpp @@ -3916,7 +3916,7 @@ void ShaderViewer::SetCurrentStep(uint32_t step) updateDebugState(); } -void ShaderViewer::ToggleBreakpoint(int instruction) +void ShaderViewer::ToggleBreakpoint(int32_t instruction) { if(!m_Trace || m_States.empty()) return; diff --git a/qrenderdoc/Windows/ShaderViewer.h b/qrenderdoc/Windows/ShaderViewer.h index ce1743529..bf599b771 100644 --- a/qrenderdoc/Windows/ShaderViewer.h +++ b/qrenderdoc/Windows/ShaderViewer.h @@ -120,7 +120,7 @@ public: virtual uint32_t CurrentStep() override; virtual void SetCurrentStep(uint32_t step) override; - virtual void ToggleBreakpoint(int instruction = -1) override; + virtual void ToggleBreakpoint(int32_t instruction = -1) override; virtual void ShowErrors(const rdcstr &errors) override; diff --git a/qrenderdoc/Windows/TextureViewer.cpp b/qrenderdoc/Windows/TextureViewer.cpp index c293ae0bf..76b72a84d 100644 --- a/qrenderdoc/Windows/TextureViewer.cpp +++ b/qrenderdoc/Windows/TextureViewer.cpp @@ -2143,7 +2143,7 @@ void TextureViewer::SetSelectedSubresource(Subresource sub) ui->sliceFace->setCurrentIndex(qMin(sub.slice, tex->arraysize - 1)); } -void TextureViewer::GotoLocation(int x, int y) +void TextureViewer::GotoLocation(uint32_t x, uint32_t y) { if(!m_Ctx.IsCaptureLoaded()) return; @@ -2153,8 +2153,8 @@ void TextureViewer::GotoLocation(int x, int y) if(tex == NULL) return; - x = qMin(x << m_TexDisplay.subresource.mip, int(tex->width - 1)); - y = qMin(y << m_TexDisplay.subresource.mip, int(tex->height - 1)); + x = qMin(x << m_TexDisplay.subresource.mip, uint32_t(tex->width - 1)); + y = qMin(y << m_TexDisplay.subresource.mip, uint32_t(tex->height - 1)); m_PickedPoint = QPoint(x, y); diff --git a/qrenderdoc/Windows/TextureViewer.h b/qrenderdoc/Windows/TextureViewer.h index 394947457..68a81141d 100644 --- a/qrenderdoc/Windows/TextureViewer.h +++ b/qrenderdoc/Windows/TextureViewer.h @@ -143,7 +143,7 @@ public: Subresource GetSelectedSubresource() override; void SetSelectedSubresource(Subresource sub) override; - void GotoLocation(int x, int y) override; + void GotoLocation(uint32_t x, uint32_t y) override; DebugOverlay GetTextureOverlay() override; void SetTextureOverlay(DebugOverlay overlay) override; diff --git a/qrenderdoc/Windows/TimelineBar.h b/qrenderdoc/Windows/TimelineBar.h index e0b3b35ca..81090595e 100644 --- a/qrenderdoc/Windows/TimelineBar.h +++ b/qrenderdoc/Windows/TimelineBar.h @@ -37,7 +37,7 @@ public: QSize minimumSizeHint() const override; - // IStatisticsViewer + // ITimelineBar QWidget *Widget() override { return this; } void HighlightResourceUsage(ResourceId id) override; void HighlightHistory(ResourceId id, const rdcarray &history) override; diff --git a/renderdoc/api/replay/capture_options.h b/renderdoc/api/replay/capture_options.h index c68ed3d20..4017788c7 100644 --- a/renderdoc/api/replay/capture_options.h +++ b/renderdoc/api/replay/capture_options.h @@ -47,7 +47,7 @@ struct CaptureOptions DOCUMENT(R"(Encode the current options to a string suitable for passing around between processes. :return: The encoded string, suitable for passing to :meth:`DecodeFromString`. -:rtype: ``str`` +:rtype: str )"); inline rdcstr EncodeAsString() const { @@ -63,16 +63,21 @@ struct CaptureOptions return optstr; } - DOCUMENT("Decode the options from a string, as returned by :meth:`EncodeAsString`."); - inline void DecodeFromString(const rdcstr &str) + DOCUMENT(R"(Decode the options from a string, as returned by :meth:`EncodeAsString`. Updates this +object in place. + +:param str encoded: The encoded string, as returned by :meth:`EncodeAsString`. +)"); + inline void DecodeFromString(const rdcstr &encoded) { - if(str.size() < sizeof(CaptureOptions)) + if(encoded.size() < sizeof(CaptureOptions)) return; // serialise from string with two chars per byte byte *b = (byte *)this; for(size_t i = 0; i < sizeof(CaptureOptions); i++) - *(b++) = byte(((byte(str[i * 2 + 0] - 'a') & 0xf) << 4) | (byte(str[i * 2 + 1] - 'a') & 0xf)); + *(b++) = byte(((byte(encoded[i * 2 + 0] - 'a') & 0xf) << 4) | + (byte(encoded[i * 2 + 1] - 'a') & 0xf)); } DOCUMENT(R"(Allow the application to enable vsync. diff --git a/renderdoc/api/replay/d3d11_pipestate.h b/renderdoc/api/replay/d3d11_pipestate.h index cdf46da7d..ffea43b99 100644 --- a/renderdoc/api/replay/d3d11_pipestate.h +++ b/renderdoc/api/replay/d3d11_pipestate.h @@ -343,7 +343,7 @@ struct Sampler DOCUMENT(R"(Check if the border color is used in this D3D11 sampler. :return: ``True`` if the border color is used, ``False`` otherwise. -:rtype: ``bool`` +:rtype: bool )"); bool UseBorder() const { diff --git a/renderdoc/api/replay/d3d12_pipestate.h b/renderdoc/api/replay/d3d12_pipestate.h index 3bcfd2e42..817b28deb 100644 --- a/renderdoc/api/replay/d3d12_pipestate.h +++ b/renderdoc/api/replay/d3d12_pipestate.h @@ -366,7 +366,7 @@ struct Sampler DOCUMENT(R"(Check if the border color is used in this D3D12 sampler. :return: ``True`` if the border color is used, ``False`` otherwise. -:rtype: ``bool`` +:rtype: bool )"); bool UseBorder() const { diff --git a/renderdoc/api/replay/data_types.h b/renderdoc/api/replay/data_types.h index d34092995..cfeece729 100644 --- a/renderdoc/api/replay/data_types.h +++ b/renderdoc/api/replay/data_types.h @@ -186,7 +186,7 @@ struct ResourceFormat bool operator!=(const ResourceFormat &r) const { return !(*this == r); } DOCUMENT(R"(:return: The name of the format. -:rtype: ``str`` +:rtype: str )"); rdcstr Name() const { @@ -196,7 +196,7 @@ struct ResourceFormat } DOCUMENT(R"(:return: ``True`` if the ``ResourceFormat`` is a 'special' non-regular type. -:rtype: ``bool`` +:rtype: bool )"); bool Special() const { return type != ResourceFormatType::Regular; } DOCUMENT(R"(The :class:`ResourceFormatType` of this format. If the value is not @@ -212,13 +212,13 @@ struct ResourceFormat With BGRA order this means blue is in the first byte/lowest bits, but alpha is still always expected in the last byte/uppermost bits. -:rtype: ``bool`` +:rtype: bool )"); bool BGRAOrder() const { return (flags & ResourceFormat_BGRA) != 0; } DOCUMENT(R"(Equivalent to checking if :data:`compType` is :data:`CompType.UNormSRGB` :return: ``True`` if the components are SRGB corrected on read and write. -:rtype: ``bool`` +:rtype: bool )"); bool SRGBCorrected() const { return compType == CompType::UNormSRGB; } DOCUMENT(R"(Get the subsampling rate for a YUV format. Only valid when :data:`type` is @@ -227,7 +227,7 @@ a YUV format like :attr:`ResourceFormatType.YUV8`. For other formats, 0 is returned. :return: The subsampling rate, e.g. 444 for 4:4:4 or 420 for 4:2:0 -:rtype: ``int`` +:rtype: int )"); uint32_t YUVSubsampling() const { @@ -246,7 +246,7 @@ a YUV format like :attr:`ResourceFormatType.YUV8`. For other formats, 1 is returned. :return: The number of planes -:rtype: ``int`` +:rtype: int )"); uint32_t YUVPlaneCount() const { @@ -273,7 +273,7 @@ For other formats, 1 is returned. The value should be e.g. 444 for 4:4:4 or 422 for 4:2:2. Invalid values will result in 0 being set. -:param int subsample: The new subsampling rate. +:param int subsampling: The new subsampling rate. )"); void SetYUVSubsampling(uint32_t subsampling) { @@ -1772,7 +1772,10 @@ struct ModificationValue DOCUMENT("The stencil output, or ``-1`` if not available."); int32_t stencil; - DOCUMENT("Returns whether or not this modification value is valid."); + DOCUMENT(R"( +:return: Returns whether or not this modification value is valid. +:rtype: bool +)"); bool IsValid() const { return col.uintValue[0] != 0xdeadbeef || col.uintValue[1] != 0xdeadf00d; } DOCUMENT("Sets this modification value to be invalid."); void SetInvalid() @@ -1893,7 +1896,7 @@ pixel. DOCUMENT(R"(Determine if this fragment passed all tests and wrote to the texture. :return: ``True`` if it passed all tests, ``False`` if it failed any. -:rtype: ``bool`` +:rtype: bool )"); bool Passed() const { diff --git a/renderdoc/api/replay/gl_pipestate.h b/renderdoc/api/replay/gl_pipestate.h index b2a52c423..e1cdc0504 100644 --- a/renderdoc/api/replay/gl_pipestate.h +++ b/renderdoc/api/replay/gl_pipestate.h @@ -353,7 +353,7 @@ struct Sampler DOCUMENT(R"(Check if the border color is used in this OpenGL sampler. :return: ``True`` if the border color is used, ``False`` otherwise. -:rtype: ``bool`` +:rtype: bool )"); bool UseBorder() const { diff --git a/renderdoc/api/replay/pipestate.h b/renderdoc/api/replay/pipestate.h index 39ed46b1b..0b8c09848 100644 --- a/renderdoc/api/replay/pipestate.h +++ b/renderdoc/api/replay/pipestate.h @@ -59,7 +59,7 @@ public: DOCUMENT(R"(Determines whether or not a capture is currently loaded. :return: A boolean indicating if a capture is currently loaded. -:rtype: ``bool`` +:rtype: bool )"); bool IsCaptureLoaded() const { @@ -69,7 +69,7 @@ public: DOCUMENT(R"(Determines whether or not a D3D11 capture is currently loaded. :return: A boolean indicating if a D3D11 capture is currently loaded. -:rtype: ``bool`` +:rtype: bool )"); bool IsCaptureD3D11() const { @@ -79,7 +79,7 @@ public: DOCUMENT(R"(Determines whether or not a D3D12 capture is currently loaded. :return: A boolean indicating if a D3D12 capture is currently loaded. -:rtype: ``bool`` +:rtype: bool )"); bool IsCaptureD3D12() const { @@ -89,7 +89,7 @@ public: DOCUMENT(R"(Determines whether or not an OpenGL capture is currently loaded. :return: A boolean indicating if an OpenGL capture is currently loaded. -:rtype: ``bool`` +:rtype: bool )"); bool IsCaptureGL() const { @@ -99,7 +99,7 @@ public: DOCUMENT(R"(Determines whether or not a Vulkan capture is currently loaded. :return: A boolean indicating if a Vulkan capture is currently loaded. -:rtype: ``bool`` +:rtype: bool )"); bool IsCaptureVK() const { @@ -111,7 +111,7 @@ public: DOCUMENT(R"(Determines whether or not tessellation is currently enabled. :return: A boolean indicating if tessellation is currently enabled. -:rtype: ``bool`` +:rtype: bool )"); bool IsTessellationEnabled() const { @@ -133,13 +133,16 @@ public: return false; } - DOCUMENT("Returns the number of views being broadcast to simultaneously during rendering."); + DOCUMENT(R"( +:return: The number of views being broadcast to simultaneously during rendering. +:rtype: int +)"); uint32_t MultiviewBroadcastCount() const; DOCUMENT(R"(Determines whether or not the current capture supports binding arrays of resources. :return: A boolean indicating if binding arrays of resources is supported. -:rtype: ``bool`` +:rtype: bool )"); bool SupportsResourceArrays() const { @@ -148,7 +151,7 @@ public: DOCUMENT(R"(Determines whether or not the current capture uses explicit barriers. :return: A boolean indicating if explicit barriers are used. -:rtype: ``bool`` +:rtype: bool )"); bool SupportsBarriers() const { return IsCaptureLoaded() && (IsCaptureVK() || IsCaptureD3D12()); } DOCUMENT(R"(Determines whether or not the PostVS data is aligned in the typical fashion (ie. @@ -158,7 +161,7 @@ requirements. :param MeshDataStage stage: The mesh data stage for the output data. :return: A boolean indicating if post-VS data is aligned. -:rtype: ``bool`` +:rtype: bool )"); bool HasAlignedPostVSData(MeshDataStage stage) const { @@ -166,8 +169,9 @@ requirements. } DOCUMENT(R"(For APIs that have explicit barriers, retrieves the current layout of a resource. -:return: The name of the current resource layout. -:rtype: ``str`` +:param ResourceId id: The ID of the resource to query for +:return: The name of the current layout of the first subresource in the resource. +:rtype: str )"); rdcstr GetResourceLayout(ResourceId id) const; @@ -175,7 +179,7 @@ requirements. :param ShaderStage stage: The shader stage to abbreviate. :return: The abbreviation of the stage. -:rtype: ``str`` +:rtype: str )"); rdcstr Abbrev(ShaderStage stage) const; @@ -183,7 +187,7 @@ requirements. 'OM' or 'FBO'. :return: The abbreviation of the output stage. -:rtype: ``str`` +:rtype: str )"); rdcstr OutputAbbrev() const; @@ -193,7 +197,7 @@ requirements. :return: The viewport for the given index. :rtype: Viewport )"); - Viewport GetViewport(int index) const; + Viewport GetViewport(uint32_t index) const; DOCUMENT(R"(Retrieves the scissor region for a given index. @@ -201,7 +205,7 @@ requirements. :return: The scissor region for the given index. :rtype: Scissor )"); - Scissor GetScissor(int index) const; + Scissor GetScissor(uint32_t index) const; DOCUMENT(R"(Retrieves the current bindpoint mapping for a shader stage. @@ -219,7 +223,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: :class:`ShaderReflection` or ``None`` +:rtype: ShaderReflection )"); const ShaderReflection *GetShaderReflection(ShaderStage stage) const; @@ -243,7 +247,7 @@ For some APIs that don't distinguish by entry point, this may be empty. :param ShaderStage stage: The shader stage to fetch. :return: The entry point name for the given shader. -:rtype: ``str`` +:rtype: str )"); rdcstr GetShaderEntryPoint(ShaderStage stage) const; @@ -258,36 +262,35 @@ For some APIs that don't distinguish by entry point, this may be empty. DOCUMENT(R"(Retrieves the current index buffer binding. :return: A :class:`BoundVBuffer` with the index buffer details. The stride is always 0. -:rtype: ``BoundVBuffer`` +:rtype: BoundVBuffer )"); BoundVBuffer GetIBuffer() const; DOCUMENT(R"(Determines whether or not primitive restart is enabled. :return: A boolean indicating if primitive restart is enabled. -:rtype: ``bool`` +:rtype: bool )"); bool IsStripRestartEnabled() const; DOCUMENT(R"(Retrieves the primitive restart index. -:param int indexByteWidth: The width in bytes of the indices. :return: The index value that represents a strip restart not a real index. -:rtype: ``int`` +:rtype: int )"); uint32_t GetStripRestartIndex() const; DOCUMENT(R"(Retrieves the currently bound vertex buffers. :return: The list of bound vertex buffers. -:rtype: ``list`` of :class:`BoundVBuffer`. +:rtype: List[BoundVBuffer] )"); rdcarray GetVBuffers() const; DOCUMENT(R"(Retrieves the currently specified vertex attributes. :return: The list of current vertex attributes. -:rtype: ``list`` of :class:`VertexInputAttribute`. +:rtype: List[VertexInputAttribute] )"); rdcarray GetVertexInputs() const; @@ -308,7 +311,7 @@ For some APIs that don't distinguish by entry point, this may be empty. :param bool onlyUsed: Return only a subset of resources containing those actually used by the shader. :return: The currently bound read-only resources. -:rtype: ``list`` of :class:`BoundResourceArray` entries +:rtype: List[BoundResourceArray] )"); rdcarray GetReadOnlyResources(ShaderStage stage, bool onlyUsed = false) const; @@ -316,7 +319,7 @@ For some APIs that don't distinguish by entry point, this may be empty. :param ShaderStage stage: The shader stage to fetch from. :return: The currently bound sampler resources. -:rtype: ``list`` of :class:`BoundResourceArray` entries +:rtype: List[BoundResourceArray] )"); rdcarray GetSamplers(ShaderStage stage) const; @@ -326,7 +329,7 @@ For some APIs that don't distinguish by entry point, this may be empty. :param bool onlyUsed: Return only a subset of resources containing those actually used by the shader. :return: The currently bound read/write resources. -:rtype: ``list`` of :class:`BoundResourceArray` entries +:rtype: List[BoundResourceArray] )"); rdcarray GetReadWriteResources(ShaderStage stage, bool onlyUsed = false) const; @@ -340,21 +343,21 @@ For some APIs that don't distinguish by entry point, this may be empty. DOCUMENT(R"(Retrieves the resources bound to the color outputs. :return: The currently bound output targets. -:rtype: ``list`` of :class:`BoundResource`. +:rtype: List[BoundResource] )"); rdcarray GetOutputTargets() const; DOCUMENT(R"(Retrieves the current color blending states, per target. :return: The currently color blend states. -:rtype: ``list`` of :class:`ColorBlend`. +:rtype: List[ColorBlend] )"); rdcarray GetColorBlends() const; DOCUMENT(R"(Determines whether or not independent blending is enabled. :return: A boolean indicating if independent blending is enabled. -:rtype: ``bool`` +:rtype: bool )"); bool IsIndependentBlendingEnabled() const; diff --git a/renderdoc/api/replay/pipestate.inl b/renderdoc/api/replay/pipestate.inl index 6ff791266..1b96449db 100644 --- a/renderdoc/api/replay/pipestate.inl +++ b/renderdoc/api/replay/pipestate.inl @@ -168,25 +168,25 @@ const VKPipe::Shader &PipeState::GetVulkanStage(ShaderStage stage) const return m_Vulkan->computeShader; } -Viewport PipeState::GetViewport(int index) const +Viewport PipeState::GetViewport(uint32_t index) const { Viewport ret = {}; if(IsCaptureLoaded()) { - if(IsCaptureD3D11() && index < m_D3D11->rasterizer.viewports.count()) + if(IsCaptureD3D11() && index < m_D3D11->rasterizer.viewports.size()) { return m_D3D11->rasterizer.viewports[index]; } - else if(IsCaptureD3D12() && index < m_D3D12->rasterizer.viewports.count()) + else if(IsCaptureD3D12() && index < m_D3D12->rasterizer.viewports.size()) { return m_D3D12->rasterizer.viewports[index]; } - else if(IsCaptureGL() && index < m_GL->rasterizer.viewports.count()) + else if(IsCaptureGL() && index < m_GL->rasterizer.viewports.size()) { return m_GL->rasterizer.viewports[index]; } - else if(IsCaptureVK() && index < m_Vulkan->viewportScissor.viewportScissors.count()) + else if(IsCaptureVK() && index < m_Vulkan->viewportScissor.viewportScissors.size()) { return m_Vulkan->viewportScissor.viewportScissors[index].vp; } @@ -195,25 +195,25 @@ Viewport PipeState::GetViewport(int index) const return ret; } -Scissor PipeState::GetScissor(int index) const +Scissor PipeState::GetScissor(uint32_t index) const { Scissor ret = {}; if(IsCaptureLoaded()) { - if(IsCaptureD3D11() && index < m_D3D11->rasterizer.viewports.count()) + if(IsCaptureD3D11() && index < m_D3D11->rasterizer.viewports.size()) { return m_D3D11->rasterizer.scissors[index]; } - else if(IsCaptureD3D12() && index < m_D3D12->rasterizer.viewports.count()) + else if(IsCaptureD3D12() && index < m_D3D12->rasterizer.viewports.size()) { return m_D3D12->rasterizer.scissors[index]; } - else if(IsCaptureGL() && index < m_GL->rasterizer.viewports.count()) + else if(IsCaptureGL() && index < m_GL->rasterizer.viewports.size()) { return m_GL->rasterizer.scissors[index]; } - else if(IsCaptureVK() && index < m_Vulkan->viewportScissor.viewportScissors.count()) + else if(IsCaptureVK() && index < m_Vulkan->viewportScissor.viewportScissors.size()) { return m_Vulkan->viewportScissor.viewportScissors[index].scissor; } diff --git a/renderdoc/api/replay/renderdoc_replay.h b/renderdoc/api/replay/renderdoc_replay.h index 5cc7973d1..cf9cec384 100644 --- a/renderdoc/api/replay/renderdoc_replay.h +++ b/renderdoc/api/replay/renderdoc_replay.h @@ -186,6 +186,9 @@ inline const WindowingData CreateAndroidWindowingData(ANativeWindow *window) return ret; } +typedef void *NSView; +typedef void *CALayer; + DOCUMENT(R"(Create a :class:`WindowingData` for an metal/opengl-compatible macOS ``CALayer`` handle and ``NSView`` handle (as void pointers). @@ -194,7 +197,7 @@ and ``NSView`` handle (as void pointers). :return: A :class:`WindowingData` corresponding to the given window. :rtype: WindowingData )"); -inline const WindowingData CreateMacOSWindowingData(void *view, void *layer) +inline const WindowingData CreateMacOSWindowingData(NSView view, CALayer layer) { WindowingData ret = {}; @@ -224,11 +227,17 @@ outputs. )"); virtual void Shutdown() = 0; - DOCUMENT("Sets the :class:`TextureDisplay` configuration for a texture output."); - virtual void SetTextureDisplay(const TextureDisplay &o) = 0; + DOCUMENT(R"(Sets the configuration for a texture output. - DOCUMENT("Sets the :class:`MeshDisplay` configuration for a mesh output."); - virtual void SetMeshDisplay(const MeshDisplay &o) = 0; +:param TextureDisplay config: The configuration. +)"); + virtual void SetTextureDisplay(const TextureDisplay &config) = 0; + + DOCUMENT(R"(Sets the configuration for a mesh output. + +:param MeshDisplay config: The configuration. +)"); + virtual void SetMeshDisplay(const MeshDisplay &config) = 0; DOCUMENT(R"(Sets the dimensions of the output, useful only for headless outputs that don't have a backing window which don't have any implicit dimensions. This allows configuring a virtual viewport @@ -245,14 +254,14 @@ which is useful for operations like picking vertices that depends on the output the output data is not displayed anywhere natively. :return: The output texture data as tightly packed RGB 3-byte data. -:rtype: ``bytes`` +:rtype: bytes )"); virtual bytebuf ReadbackOutputTexture() = 0; DOCUMENT(R"(Retrieve the current dimensions of the output. :return: The current width and height of the output. -:rtype: ``pair`` of two ``int`` +:rtype: Tuple[int,int] )"); virtual rdcpair GetDimensions() = 0; @@ -278,7 +287,7 @@ Should only be called for texture outputs. texture data will be reinterpreted - e.g. from unsigned integers to floats, or to unsigned normalised values. :return: A boolean indicating if the thumbnail was successfully created. -:rtype: ``bool`` +:rtype: bool )"); virtual bool AddThumbnail(WindowingData window, ResourceId textureId, const Subresource &sub, CompType typeCast) = 0; @@ -298,13 +307,16 @@ Should only be called for texture outputs. :param WindowingData window: A :class:`WindowingData` describing the native window. :return: A boolean indicating if the pixel context was successfully configured. -:rtype: ``bool`` +:rtype: bool )"); virtual bool SetPixelContext(WindowingData window) = 0; DOCUMENT(R"(Sets the pixel that the pixel context should be centred on. Should only be called for texture outputs. + +:param int x: The X co-ordinate to highlight. +:param int y: The Y co-ordinate to highlight. )"); virtual void SetPixelContextLocation(uint32_t x, uint32_t y) = 0; @@ -346,7 +358,7 @@ Should only be called for mesh outputs. :param int y: The y co-ordinate to pick from. :return: A tuple with the first value being the vertex index in the mesh, and the second value being the instance index. The values are set to :data:`NoResult` if no vertex was found, -:rtype: ``tuple`` of ``int`` and ``int`` +:rtype: Tuple[int,int] )"); virtual rdcpair PickVertex(uint32_t x, uint32_t y) = 0; @@ -367,7 +379,7 @@ well as control the replay and analysis functionality available. Called whenever some on-going blocking process needs to determine if it should close. :return: Whether or not the process should be killed. - :rtype: ``bool`` + :rtype: bool .. function:: ProgressCallback() @@ -409,7 +421,7 @@ struct IReplayController DOCUMENT(R"(Retrieves the supported :class:`WindowingSystem` systems by the local system. :return: The list of supported systems. -:rtype: ``list`` of :class:`WindowingSystem` +:rtype: List[WindowingSystem] )"); virtual rdcarray GetSupportedWindowSystems() = 0; @@ -524,7 +536,7 @@ or hardware-specific ISA formats. :param bool withPipeline: More disassembly may be available when a pipeline is specified. :return: The list of disassembly targets available. -:rtype: ``list`` of ``str`` +:rtype: List[str] )"); virtual rdcarray GetDisassemblyTargets(bool withPipeline) = 0; @@ -535,7 +547,7 @@ or hardware-specific ISA formats. :param str target: The name of the disassembly target to generate for. Must be one of the values returned by :meth:`GetDisassemblyTargets`, or empty to use the default generation. :return: The disassembly text, or an error message if something went wrong. -:rtype: ``str`` +:rtype: str )"); virtual rdcstr DisassembleShader(ResourceId pipeline, const ShaderReflection *refl, const rdcstr &target) = 0; @@ -547,11 +559,11 @@ See :data:`TextureDisplay.customShaderId`. :param str entry: The entry point to use when compiling. :param ShaderEncoding sourceEncoding: The encoding of the source data. :param bytes source: The source data itself. -:param int compileFlags: API-specific compilation flags. +:param ShaderCompileFlags compileFlags: API-specific compilation flags. :param ShaderStage type: The stage that this shader will be executed at. :return: A ``tuple`` with the id of the new shader if compilation was successful, :meth:`ResourceId.Null` otherwise, and a ``str`` with any warnings/errors from compilation. -:rtype: ``tuple`` of :class:`ResourceId` and ``str``. +:rtype: Tuple[ResourceId,str] )"); virtual rdcpair BuildCustomShader(const rdcstr &entry, ShaderEncoding sourceEncoding, bytebuf source, @@ -575,11 +587,11 @@ See :meth:`BuildCustomShader`. :param ShaderStage type: The stage that this shader will be executed at. :return: A ``tuple`` with the id of the new shader if compilation was successful, :meth:`ResourceId.Null` otherwise, and a ``str`` with any warnings/errors from compilation. -:rtype: ``tuple`` of :class:`ResourceId` and ``str``. +:rtype: Tuple[ResourceId,str] )"); virtual rdcpair BuildTargetShader(const rdcstr &entry, ShaderEncoding sourceEncoding, bytebuf source, - const ShaderCompileFlags &flags, + const ShaderCompileFlags &compileFlags, ShaderStage type) = 0; DOCUMENT(R"(Retrieve the list of supported :class:`ShaderEncoding` which can be build using @@ -593,7 +605,7 @@ compiled internally - so compiling externally could be preferable as it allows b of the compile process or using alternate/updated tools. :return: The list of target shader encodings available. -:rtype: ``list`` of :class:`ShaderEncoding` +:rtype: List[ShaderEncoding] )"); virtual rdcarray GetTargetShaderEncodings() = 0; @@ -608,7 +620,7 @@ compiled internally - so compiling externally could be preferable as it allows b of the compile process or using alternate/updated tools. :return: The list of target shader encodings available. -:rtype: ``list`` of :class:`ShaderEncoding` +:rtype: List[ShaderEncoding] )"); virtual rdcarray GetCustomShaderEncodings() = 0; @@ -662,15 +674,15 @@ textures are bound as outputs. DOCUMENT(R"(Retrieve the list of root-level drawcalls in the capture. :return: The list of root-level drawcalls in the capture. -:rtype: ``list`` of :class:`DrawcallDescription` +:rtype: List[DrawcallDescription] )"); virtual const rdcarray &GetDrawcalls() = 0; DOCUMENT(R"(Retrieve the values of a specified set of counters. -:param list counters: The list of :class:`GPUCounter` to fetch results for. +:param List[GPUCounter] counters: The list of counters to fetch results for. :return: The list of counter results generated. -:rtype: ``list`` of :class:`CounterResult` +:rtype: List[CounterResult] )"); virtual rdcarray FetchCounters(const rdcarray &counters) = 0; @@ -678,7 +690,7 @@ textures are bound as outputs. implementation. :return: The list of counters available. -:rtype: ``list`` of :class:`GPUCounter` +:rtype: List[GPUCounter] )"); virtual rdcarray EnumerateCounters() = 0; @@ -697,21 +709,21 @@ This includes any object allocated a :class:`ResourceId`, that don't have any ot are only used as intermediary elements. :return: The list of resources in the capture. -:rtype: ``list`` of :class:`ResourceDescription` +:rtype: List[ResourceDescription] )"); virtual const rdcarray &GetResources() = 0; DOCUMENT(R"(Retrieve the list of textures alive in the capture. :return: The list of textures in the capture. -:rtype: ``list`` of :class:`TextureDescription` +:rtype: List[TextureDescription] )"); virtual const rdcarray &GetTextures() = 0; DOCUMENT(R"(Retrieve the list of buffers alive in the capture. :return: The list of buffers in the capture. -:rtype: ``list`` of :class:`BufferDescription` +:rtype: List[BufferDescription] )"); virtual const rdcarray &GetBuffers() = 0; @@ -721,7 +733,7 @@ Every time this function is called, any debug messages returned will not be retu newly generated messages will be returned after that. :return: The list of the :class:`DebugMessage` messages. -:rtype: ``list`` of :class:`DebugMessage` +:rtype: List[DebugMessage] )"); virtual rdcarray GetDebugMessages() = 0; @@ -732,7 +744,7 @@ only ever have one result (only one entry point per shader). :param ResourceId shader: The shader to look up entry points for. :return: The list of the :class:`ShaderEntryPoint` messages. -:rtype: ``list`` of :class:`ShaderEntryPoint` +:rtype: List[ShaderEntryPoint] )"); virtual rdcarray GetShaderEntryPoints(ResourceId shader) = 0; @@ -779,7 +791,7 @@ only ever have one result (only one entry point per shader). texture data will be reinterpreted - e.g. from unsigned integers to floats, or to unsigned normalised values. :return: A tuple with the minimum and maximum pixel values respectively. -:rtype: ``tuple`` of PixelValue and PixelValue +:rtype: Tuple[PixelValue,PixelValue] )"); virtual rdcpair GetMinMax(ResourceId textureId, const Subresource &sub, CompType typeCast) = 0; @@ -800,10 +812,10 @@ bucket when the pixel values are divided between ``minval`` and ``maxval``. not added to any bucket. :param float maxval: The upper end of the largest bucket. If any values are above this, they are not added to any bucket. -:param list channels: A list of four ``bool`` values indicating whether each of RGBA should be - included in the count. +:param Tuple[bool,bool,bool,bool] channels: A set of four flags indicating whether each of RGBA + respectively should be included in the count. :return: A list of the unnormalised bucket values. -:rtype: ``list`` of ``int`` +:rtype: List[int] )"); virtual rdcarray GetHistogram(ResourceId textureId, const Subresource &sub, CompType typeCast, float minval, float maxval, @@ -821,13 +833,12 @@ bucket when the pixel values are divided between ``minval`` and ``maxval``. :param int x: The x co-ordinate. :param int y: The y co-ordinate. :param Subresource sub: The subresource within this texture to use. -:param int sampleIdx: The multi-sampled sample. Ignored if non-multisampled texture. :param CompType typeCast: If possible interpret the texture with this type instead of its normal type. If set to :data:`CompType.Typeless` then no cast is applied, otherwise where allowed the texture data will be reinterpreted - e.g. from unsigned integers to floats, or to unsigned normalised values. :return: The list of pixel history events. -:rtype: ``list`` of :class:`PixelModification` +:rtype: List[PixelModification] )"); virtual rdcarray PixelHistory(ResourceId texture, uint32_t x, uint32_t y, const Subresource &sub, CompType typeCast) = 0; @@ -868,8 +879,8 @@ bucket when the pixel values are divided between ``minval`` and ``maxval``. DOCUMENT(R"(Retrieve a debugging trace from running a compute thread. -:param groupid: A list containing the 3D workgroup index. -:param threadid: A list containing the 3D thread index within the above workgroup. +:param Tuple[int,int,int] groupid: A list containing the 3D workgroup index. +:param Tuple[int,int,int] threadid: A list containing the 3D thread index within the workgroup. :return: The resulting trace resulting from debugging. Destroy with :meth:`FreeTrace`. :rtype: ShaderDebugTrace @@ -886,7 +897,7 @@ completed, further calls will return an empty list. :param ShaderDebugger debugger: The shader debugger to continue running. :return: A number of subsequent states. -:rtype: ``list`` of :class:`ShaderDebugTrace` +:rtype: List[ShaderDebugState] )"); virtual rdcarray ContinueDebug(ShaderDebugger *debugger) = 0; @@ -900,7 +911,7 @@ completed, further calls will return an empty list. :param ResourceId id: The id of the texture or buffer resource to be queried. :return: The list of usages of the resource. -:rtype: ``list`` of :class:`EventUsage` +:rtype: List[EventUsage] )"); virtual rdcarray GetUsage(ResourceId id) = 0; @@ -917,7 +928,7 @@ otherwise. :param int length: Retrieve this many bytes after :paramref:`offset`. May be 0 to fetch the rest of the buffer. :return: The shader variables with their contents. -:rtype: ``list`` of :class:`ShaderVariable` +:rtype: List[ShaderVariable] )"); virtual rdcarray GetCBufferVariableContents(ResourceId pipeline, ResourceId shader, const rdcstr &entryPoint, @@ -930,7 +941,7 @@ texture to something compatible with the target file format. :param TextureSave saveData: The configuration settings of which texture to save, and how :param str path: The path to save to on disk. :return: ``True`` if the texture was saved successfully, ``False`` otherwise. -:rtype: ``bool`` +:rtype: bool )"); virtual bool SaveTexture(const TextureSave &saveData, const rdcstr &path) = 0; @@ -950,7 +961,7 @@ texture to something compatible with the target file format. :param int offset: The byte offset to the start of the range. :param int len: The length of the range, or 0 to retrieve the rest of the bytes in the buffer. :return: The requested buffer contents. -:rtype: ``bytes`` +:rtype: bytes )"); virtual bytebuf GetBufferData(ResourceId buff, uint64_t offset, uint64_t len) = 0; @@ -959,7 +970,7 @@ texture to something compatible with the target file format. :param ResourceId tex: The id of the texture to retrieve data from. :param Subresource sub: The subresource within this texture to use. :return: The requested texture contents. -:rtype: ``bytes`` +:rtype: bytes )"); virtual bytebuf GetTextureData(ResourceId tex, const Subresource &sub) = 0; @@ -983,35 +994,35 @@ struct ITargetControl DOCUMENT(R"(Determines if the connection is still alive. :return: ``True`` if the connection still appears to be working, ``False`` if it has been closed. -:rtype: ``bool`` +:rtype: bool )"); virtual bool Connected() = 0; DOCUMENT(R"(Retrieves the target's name or identifier - typically the name of the executable. :return: The target name. -:rtype: ``str`` +:rtype: str )"); virtual rdcstr GetTarget() = 0; DOCUMENT(R"(Retrieves the API currently in use by the target. :return: The API name, or empty if no API is initialised yet. -:rtype: ``str`` +:rtype: str )"); virtual rdcstr GetAPI() = 0; DOCUMENT(R"(Retrieves the Process ID (PID) of the target on its local system. :return: The Process ID, or 0 if that's not applicable on the target platform. -:rtype: ``int`` +:rtype: int )"); virtual uint32_t GetPID() = 0; DOCUMENT(R"(If a busy message was received, determine the client keeping the target busy. :return: The name of the client currently connected to the target. -:rtype: ``str`` +:rtype: str )"); virtual rdcstr GetBusyClient() = 0; @@ -1087,16 +1098,16 @@ struct ICaptureAccess :class:`ReplayOptions` to force replay on a particular GPU. :return: The list of GPUs available. -:rtype: ``list`` of :class:`GPUDevice` +:rtype: List[GPUDevice] )"); virtual rdcarray GetAvailableGPUs() = 0; DOCUMENT(R"(Retrieve the total number of available sections. :return: The number of sections in the capture -:rtype: ``int``. +:rtype: int )"); - virtual int GetSectionCount() = 0; + virtual int32_t GetSectionCount() = 0; DOCUMENT(R"(Locate the index of a section by its name. Returns ``-1`` if the section is not found. @@ -1104,9 +1115,9 @@ This index should not be cached, as writing sections could re-order the indices. :param str name: The name of the section to search for. :return: The index of the section, or ``-1`` if not found. -:rtype: ``int``. +:rtype: int )"); - virtual int FindSectionByName(const rdcstr &name) = 0; + virtual int32_t FindSectionByName(const rdcstr &name) = 0; DOCUMENT(R"(Locate the index of a section by its type. Returns ``-1`` if the section is not found. @@ -1114,9 +1125,9 @@ This index should not be cached, as writing sections could re-order the indices. :param SectionType type: The type of the section to search for. :return: The index of the section, or ``-1`` if not found. -:rtype: ``int``. +:rtype: int )"); - virtual int FindSectionByType(SectionType type) = 0; + virtual int32_t FindSectionByType(SectionType type) = 0; DOCUMENT(R"(Get the describing properties of the specified section. @@ -1124,15 +1135,15 @@ This index should not be cached, as writing sections could re-order the indices. :return: The properties of the section, if the index is valid. :rtype: SectionProperties )"); - virtual SectionProperties GetSectionProperties(int index) = 0; + virtual SectionProperties GetSectionProperties(int32_t index) = 0; DOCUMENT(R"(Get the raw byte contents of the specified section. :param int index: The index of the section. :return: The raw contents of the section, if the index is valid. -:rtype: ``bytes``. +:rtype: bytes )"); - virtual bytebuf GetSectionContents(int index) = 0; + virtual bytebuf GetSectionContents(int32_t index) = 0; DOCUMENT(R"(Writes a new section with specified properties and contents. If an existing section already has the same type or name, it will be overwritten (two sections cannot share the same type @@ -1141,14 +1152,14 @@ or name). :param SectionProperties props: The properties of the section to be written. :param bytes contents: The raw contents of the section. :return: ``True`` if the section was written successfully, ``False`` otherwise. -:rtype: ``bool`` +:rtype: bool )"); virtual bool WriteSection(const SectionProperties &props, const bytebuf &contents) = 0; DOCUMENT(R"(Query if callstacks are available. :return: ``True`` if any callstacks are available, ``False`` otherwise. -:rtype: ``bool`` +:rtype: bool )"); virtual bool HasCallstacks() = 0; @@ -1165,7 +1176,7 @@ separate thread. :param ProgressCallback progress: A callback that will be repeatedly called with an updated progress value for the resolver process. Can be ``None`` if no progress is desired. :return: ``True`` if the resolver successfully initialised, ``False`` if something went wrong. -:rtype: ``bool`` +:rtype: bool )"); virtual bool InitResolver(bool interactive, RENDERDOC_ProgressCallback progress) = 0; @@ -1173,16 +1184,16 @@ separate thread. Must only be called after :meth:`InitResolver` has returned ``True``. -:param list callstack: The integer addresses in the original callstack. +:param List[int] callstack: The integer addresses in the original callstack. :return: The list of resolved callstack entries as strings. -:rtype: ``list`` of ``str`` +:rtype: List[str] )"); virtual rdcarray GetResolve(const rdcarray &callstack) = 0; DOCUMENT(R"(Retrieves the name of the driver that was used to create this capture. :return: A simple string identifying the driver used to make the capture. -:rtype: ``str`` +:rtype: str )"); virtual rdcstr DriverName() = 0; @@ -1212,7 +1223,7 @@ struct IRemoteServer : public ICaptureAccess :return: ``True`` if the ping was sent and received successfully, ``False`` if something went wrong and the connection is no longer alive. -:rtype: ``bool`` +:rtype: bool )"); virtual bool Ping() = 0; @@ -1221,7 +1232,7 @@ struct IRemoteServer : public ICaptureAccess These will be strings like "D3D11" or "OpenGL". :return: A list of names of the local proxies. -:rtype: ``list`` of ``str`` +:rtype: List[str] )"); virtual rdcarray LocalProxies() = 0; @@ -1230,14 +1241,14 @@ These will be strings like "D3D11" or "OpenGL". These will be strings like "D3D11" or "OpenGL". :return: A list of names of the remote renderers. -:rtype: ``list`` of ``str`` +:rtype: List[str] )"); virtual rdcarray RemoteSupportedReplays() = 0; DOCUMENT(R"(Retrieve the path on the remote system where browsing can begin. :return: The 'home' path where browsing for files or folders can begin. -:rtype: ``str`` +:rtype: str )"); virtual rdcstr GetHomeFolder() = 0; @@ -1247,7 +1258,7 @@ If an error occurs, a single :class:`PathEntry` will be returned with appropriat :param str path: The remote path to list. :return: The contents of the specified folder. -:rtype: ``list`` of :class:`PathEntry` +:rtype: List[PathEntry] )"); virtual rdcarray ListFolder(const rdcstr &path) = 0; @@ -1260,7 +1271,8 @@ This happens on the remote system, so all paths are relative to the remote files directory containing the application is used. :param str cmdLine: The command line to use when running the application, it will be processed in a platform specific way to generate arguments. -:param list env: Any :class:`EnvironmentModification` that should be made when running the program. +:param List[EnvironmentModification] env: Any environment changes that should be made when running + the program. :param CaptureOptions opts: The capture options to use when injecting into the program. :return: The :class:`ExecuteResult` indicating both the status of the operation (success or failure) and any reason for failure, or else the ident where the new application is listening for target @@ -1296,7 +1308,7 @@ the capture must be available on the machine where the replay happens. :param ProgressCallback progress: A callback that will be repeatedly called with an updated progress value for the copy. Can be ``None`` if no progress is desired. :return: The path on the remote system where the capture was saved temporarily. -:rtype: ``str`` +:rtype: str )"); virtual rdcstr CopyCaptureToRemote(const rdcstr &filename, RENDERDOC_ProgressCallback progress) = 0; @@ -1332,7 +1344,7 @@ or an error has occurred. 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` +:rtype: Tuple[ReplayStatus,ReplayController] )"); virtual rdcpair OpenCapture( uint32_t proxyid, const rdcstr &logfile, const ReplayOptions &opts, @@ -1404,7 +1416,7 @@ file. :param str filename: The filename to copy to. :return: ``True`` if the operation succeeded. -:rtype: ``bool`` +:rtype: bool )"); virtual bool CopyFileTo(const rdcstr &filename) = 0; @@ -1433,14 +1445,14 @@ The error string is not reset by calling this function so it's safe to call mult any other function call may reset the error string to empty. :return: The error string, if one exists, or an empty string. -:rtype: ``str`` +:rtype: str )"); virtual rdcstr ErrorString() = 0; DOCUMENT(R"(Returns the list of capture file formats. :return: The list of capture file formats available. -:rtype: ``list`` of :class:`CaptureFileFormat` +:rtype: List[CaptureFileFormat] )"); virtual rdcarray GetCaptureFileFormats() = 0; @@ -1457,7 +1469,7 @@ replay support. DOCUMENT(R"(Retrieves the identifying string describing what type of machine created this capture. :return: A string identifying the machine ident used to make the capture. -:rtype: ``str`` +:rtype: str )"); virtual rdcstr RecordedMachineIdent() = 0; @@ -1465,7 +1477,7 @@ replay support. be 0 if all timestamps are already absolute. :return: The timestamp base value -:rtype: ``int`` +:rtype: int )"); virtual uint64_t TimestampBase() = 0; @@ -1473,7 +1485,7 @@ be 0 if all timestamps are already absolute. microseconds. May be 1.0 if all timestamps and durations are already in microseconds. :return: The timestamp frequency -:rtype: ``float`` +:rtype: float )"); virtual double TimestampFrequency() = 0; @@ -1520,7 +1532,7 @@ by the :class:`ReplayController`. 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`. +:rtype: Tuple[ReplayStatus,ReplayController] )"); virtual rdcpair OpenCapture( const ReplayOptions &opts, RENDERDOC_ProgressCallback progress) = 0; @@ -1670,16 +1682,16 @@ float. :param int half: The half stored as an int. :return: The floating point equivalent. -:rtype: ``float`` +:rtype: float )"); extern "C" RENDERDOC_API float RENDERDOC_CC RENDERDOC_HalfToFloat(uint16_t half); DOCUMENT(R"(A utility function that converts a float to a half (stored in a 16-bit unsigned integer). -:param float f: The floating point value. +:param float flt: The floating point value. :return: The nearest half-float equivalent stored as an int. -:rtype: ``int`` +:rtype: int )"); extern "C" RENDERDOC_API uint16_t RENDERDOC_CC RENDERDOC_FloatToHalf(float flt); @@ -1690,7 +1702,7 @@ topology. :param Topology topology: The topology to query about. :return: The number of vertices in a single primitive. -:rtype: ``int`` +:rtype: int )"); extern "C" RENDERDOC_API uint32_t RENDERDOC_CC RENDERDOC_NumVerticesPerPrimitive(Topology topology); @@ -1701,7 +1713,7 @@ case of strip topologies. :param Topology topology: The topology to query about. :param int primitive: The primitive to query about. :return: The vertex offset where the primitive starts. -:rtype: ``int`` +:rtype: int )"); extern "C" RENDERDOC_API uint32_t RENDERDOC_CC RENDERDOC_VertexOffset(Topology topology, uint32_t primitive); @@ -1754,7 +1766,7 @@ This function will block for a variable timeout depending on how many targets ar specified then default TCP enumeration happens. :param int nextIdent: The next ident to scan. :return: The ident of the next active target, or ``0`` if no other targets exist. -:rtype: ``int`` +:rtype: int )"); extern "C" RENDERDOC_API uint32_t RENDERDOC_CC RENDERDOC_EnumerateRemoteTargets(const rdcstr &URL, uint32_t nextIdent); @@ -1769,7 +1781,7 @@ DOCUMENT(R"(Create a connection to a remote server running on given hostname. specified then default TCP enumeration happens. :return: The status of opening the connection, whether success or failure, and a :class:`RemoteServer` instance if it were successful -:rtype: ``pair`` of ReplayStatus and RemoteServer +:rtype: Tuple[ReplayStatus,RemoteServer] )"); extern "C" RENDERDOC_API ReplayStatus RENDERDOC_CC RENDERDOC_CreateRemoteServerConnection(const rdcstr &URL, IRemoteServer **rend); @@ -1793,7 +1805,7 @@ from external sources. This function will block until a remote connection tells the server to shut down, or the ``killReplay`` callback returns ``True``. -:param str host: The name of the interface to listen on. +:param str listenhost: The name of the interface to listen on. :param KillCallback killReplay: A callback that returns a ``bool`` indicating if the server should be shut down or not. :param PreviewWindowCallback previewWindow: A callback that returns information for a preview window @@ -1830,7 +1842,7 @@ This function must be called when the process is running with administrator/supe :param CaptureOptions opts: The capture options to use when injecting into the program. :return: ``True`` if the hook is active, ``False`` if something went wrong. The hook must be closed with :func:`StopGlobalHook` before the application is closed. -:rtype: ``bool`` +:rtype: bool )"); extern "C" RENDERDOC_API bool RENDERDOC_CC RENDERDOC_StartGlobalHook(const rdcstr &pathmatch, const rdcstr &logfile, @@ -1848,14 +1860,14 @@ DOCUMENT(R"(Determines if the global hook is active or not. This function can only be called if global hooking is supported (see :func:`CanGlobalHook`). :return: ``True`` if the hook is active, or ``False`` if the hook is inactive. -:rtype: ``bool`` +:rtype: bool )"); extern "C" RENDERDOC_API bool RENDERDOC_CC RENDERDOC_IsGlobalHookActive(); DOCUMENT(R"(Determines if the global hook is supported on the current platform and configuration. :return: ``True`` if global hooking can be used on the platform, ``False`` if not. -:rtype: ``bool`` +:rtype: bool )"); extern "C" RENDERDOC_API bool RENDERDOC_CC RENDERDOC_CanGlobalHook(); @@ -1866,7 +1878,8 @@ DOCUMENT(R"(Launch an application and inject into it to allow capturing. directory containing the application is used. :param str cmdLine: The command line to use when running the application, it will be processed in a platform specific way to generate arguments. -:param list env: Any :class:`EnvironmentModification` that should be made when running the program. +:param List[EnvironmentModification] env: Any environment changes that should be made when running + the program. :param str capturefile: The capture file path template, or blank to use a default location. :param CaptureOptions opts: The capture options to use when injecting into the program. :param bool waitForExit: If ``True`` this function will block until the process exits. @@ -1883,7 +1896,8 @@ RENDERDOC_ExecuteAndInject(const rdcstr &app, const rdcstr &workingDir, const rd DOCUMENT(R"(Where supported by operating system and permissions, inject into a running process. :param int pid: The Process ID (PID) to inject into. -:param list env: Any :class:`EnvironmentModification` that should be made when running the program. +:param List[EnvironmentModification] env: Any environment changes that should be made when running + the program. :param str capturefile: The capture file path template, or blank to use a default location. :param CaptureOptions opts: The capture options to use when injecting into the program. :param bool waitForExit: If ``True`` this function will block until the process exits. @@ -1948,9 +1962,9 @@ has been called. It should be called exactly once, and before shutdown you must :func:`ShutdownReplay`. :param GlobalEnvironment globalEnv: The path to the new log file. -:param ``list`` of ``str`` args: Any extra command-line arguments. +:param List[str] args: Any extra command-line arguments. )"); -extern "C" RENDERDOC_API void RENDERDOC_CC RENDERDOC_InitialiseReplay(GlobalEnvironment env, +extern "C" RENDERDOC_API void RENDERDOC_CC RENDERDOC_InitialiseReplay(GlobalEnvironment globalEnv, const rdcarray &args); DOCUMENT(R"(Shutdown RenderDoc for replay. Replay API functions should not be called after this @@ -1984,7 +1998,7 @@ DOCUMENT(R"(Gets the location for the diagnostic log output, shared by captured analysis program. :return: The path to the current log file. -:rtype: ``str`` +:rtype: str )"); extern "C" RENDERDOC_API const char *RENDERDOC_CC RENDERDOC_GetLogFile(); @@ -2004,7 +2018,7 @@ DOCUMENT(R"(Add a message to RenderDoc's logfile. :param str text: The text of the message. )"); extern "C" RENDERDOC_API void RENDERDOC_CC RENDERDOC_LogMessage(LogType type, const rdcstr &project, - const rdcstr &file, unsigned int line, + const rdcstr &file, uint32_t line, const rdcstr &text); DOCUMENT(R"(Retrieves the version string. @@ -2012,14 +2026,14 @@ DOCUMENT(R"(Retrieves the version string. This will be in the form "MAJOR.MINOR" :return: The version string. -:rtype: ``str`` +:rtype: str )"); extern "C" RENDERDOC_API const char *RENDERDOC_CC RENDERDOC_GetVersionString(); DOCUMENT(R"(Determines if this is a release build of RenderDoc or not. :return: ``True`` if the replay is running on a release build. -:rtype: ``bool`` +:rtype: bool )"); extern "C" RENDERDOC_API bool RENDERDOC_CC RENDERDOC_IsReleaseBuild(); @@ -2028,7 +2042,7 @@ DOCUMENT(R"(Retrieves the commit hash used to build. This will be in the form "0123456789abcdef0123456789abcdef01234567" :return: The commit hash. -:rtype: ``str`` +:rtype: str )"); extern "C" RENDERDOC_API const char *RENDERDOC_CC RENDERDOC_GetCommitHash(); @@ -2043,7 +2057,7 @@ extern "C" RENDERDOC_API DriverInformation RENDERDOC_CC RENDERDOC_GetDriverInfor DOCUMENT(R"(Returns the current process's memory usage in bytes :return: The current memory usage in bytes. -:rtype: ``int`` +:rtype: int )"); extern "C" RENDERDOC_API uint64_t RENDERDOC_CC RENDERDOC_GetCurrentProcessMemoryUsage(); @@ -2056,8 +2070,9 @@ the setting's value, description, etc. If no such setting exists, `None` is returned. +:param str name: The name of the setting. :return: The specified setting. -:rtype: ``SDObject`` +:rtype: SDObject )"); extern "C" RENDERDOC_API const SDObject *RENDERDOC_CC RENDERDOC_GetConfigSetting(const rdcstr &name); @@ -2066,8 +2081,9 @@ value object. If no such setting exists, `None` is returned. +:param str name: The name of the setting. :return: The specified setting. -:rtype: ``SDObject`` +:rtype: SDObject )"); extern "C" RENDERDOC_API SDObject *RENDERDOC_CC RENDERDOC_SetConfigSetting(const rdcstr &name); @@ -2104,7 +2120,7 @@ struct IDeviceProtocolController DOCUMENT(R"(Retrieves the name of this protocol as passed to :func:`GetDeviceProtocolController`. :return: A string identifying the protocol. -:rtype: ``str`` +:rtype: str )"); virtual rdcstr GetProtocolName() = 0; @@ -2118,7 +2134,7 @@ The returned string is the hostname of the device, which can be connected via ``protocol://hostname`` with interfaces that take a hostname. :return: A list of the devices currently available. -:rtype: ``list`` of ``str`` +:rtype: List[str] )"); virtual rdcarray GetDevices() = 0; @@ -2128,7 +2144,7 @@ correlate to a device than the hostname which may be only a programmatic identif :param str URL: The URL of the device in the form ``protocol://host``, with protocol as returned by :func:`GetProtocolName` and host as returned by :func:`GetDevices`. :return: A string identifying the device. -:rtype: ``str`` +:rtype: str )"); virtual rdcstr GetFriendlyName(const rdcstr &URL) = 0; @@ -2138,7 +2154,7 @@ user can be prompted to close an existing program before a new one is launched. :param str URL: The URL of the device in the form ``protocol://host``, with protocol as returned by :func:`GetProtocolName` and host as returned by :func:`GetDevices`. :return: ``True`` if the device supports multiple programs, ``False`` otherwise. -:rtype: ``bool`` +:rtype: bool )"); virtual bool SupportsMultiplePrograms(const rdcstr &URL) = 0; @@ -2147,7 +2163,7 @@ user can be prompted to close an existing program before a new one is launched. :param str URL: The URL of the device in the form ``protocol://host``, with protocol as returned by :func:`GetProtocolName` and host as returned by :func:`GetDevices`. :return: ``True`` if any the device is supported, ``False`` otherwise. -:rtype: ``bool`` +:rtype: bool )"); virtual bool IsSupported(const rdcstr &URL) = 0; @@ -2168,7 +2184,7 @@ protected: DOCUMENT(R"(Retrieve the set of device protocols supported (see :func:`GetDeviceProtocolController`). :return: The supported device protocols. -:rtype: ``list`` of ``str`` +:rtype: List[str] )"); extern "C" RENDERDOC_API void RENDERDOC_CC RENDERDOC_GetSupportedDeviceProtocols(rdcarray *supportedProtocols); diff --git a/renderdoc/api/replay/replay_enums.h b/renderdoc/api/replay/replay_enums.h index 00712c3df..4cf533347 100644 --- a/renderdoc/api/replay/replay_enums.h +++ b/renderdoc/api/replay/replay_enums.h @@ -1735,6 +1735,7 @@ DOCUMENT(R"(Check if an API is D3D or not :param GraphicsAPI api: The graphics API in question :return: ``True`` if api is a D3D-based API, ``False`` otherwise +:rtype: bool )"); constexpr inline bool IsD3D(GraphicsAPI api) { @@ -1785,9 +1786,9 @@ DECLARE_REFLECTION_ENUM(ShaderEncoding); DOCUMENT(R"(Check whether or not this is a human readable text representation. -:param ShaderEncoding e: The encoding to check. +:param ShaderEncoding encoding: The encoding to check. :return: ``True`` if it describes a text representation, ``False`` for a bytecode representation. -:rtype: ``bool`` +:rtype: bool )"); constexpr inline bool IsTextRepresentation(ShaderEncoding encoding) { @@ -2047,9 +2048,9 @@ DOCUMENT(R"(Return the number of control points in a patch list ``Topology`` ``t`` must be a patch list topology, the return value will be between 1 and 32 inclusive -:param Topology t: The patch list topology +:param Topology topology: The patch list topology :return: The number of control points in the specified topology -:rtype: ``int`` +:rtype: int )"); constexpr inline uint32_t PatchList_Count(Topology topology) { @@ -2063,9 +2064,9 @@ DOCUMENT(R"(Check whether or not this topology supports primitive restart. .. note:: This is almost but not quite the same as being a line/triangle strip - triangle fans also support restart. See also :func:`IsStrip`. -:param Topology t: The topology to check. +:param Topology topology: The topology to check. :return: ``True`` if it describes a topology that allows restart, ``False`` for a list. -:rtype: ``bool`` +:rtype: bool )"); constexpr inline bool SupportsRestart(Topology topology) { @@ -2076,9 +2077,9 @@ constexpr inline bool SupportsRestart(Topology topology) DOCUMENT(R"(Check whether or not this is a strip-type topology. -:param Topology t: The topology to check. +:param Topology topology: The topology to check. :return: ``True`` if it describes a strip topology, ``False`` for a list. -:rtype: ``bool`` +:rtype: bool )"); constexpr inline bool IsStrip(Topology topology) { @@ -3297,7 +3298,7 @@ DOCUMENT(R"(Check whether or not this is a Generic counter. :param GPUCounter c: The counter. :return: ``True`` if it is a generic counter, ``False`` if it's not. -:rtype: ``bool`` +:rtype: bool )"); inline constexpr bool IsGenericCounter(GPUCounter c) { @@ -3308,7 +3309,7 @@ DOCUMENT(R"(Check whether or not this is an AMD private counter. :param GPUCounter c: The counter. :return: ``True`` if it is an AMD private counter, ``False`` if it's not. -:rtype: ``bool`` +:rtype: bool )"); inline constexpr bool IsAMDCounter(GPUCounter c) { @@ -3319,7 +3320,7 @@ DOCUMENT(R"(Check whether or not this is an Intel private counter. :param GPUCounter c: The counter. :return: ``True`` if it is an Intel private counter, ``False`` if it's not. -:rtype: ``bool`` +:rtype: bool )"); inline constexpr bool IsIntelCounter(GPUCounter c) { @@ -3330,7 +3331,7 @@ DOCUMENT(R"(Check whether or not this is an Nvidia private counter. :param GPUCounter c: The counter. :return: ``True`` if it is an Nvidia private counter, ``False`` if it's not. -:rtype: ``bool`` +:rtype: bool )"); inline constexpr bool IsNvidiaCounter(GPUCounter c) { @@ -3341,7 +3342,7 @@ DOCUMENT(R"(Check whether or not this is a KHR counter. :param GPUCounter c: The counter. :return: ``True`` if it is a Vulkan counter reported through the VK_KHR_performance_query extension, ``False`` if it's not. -:rtype: ``bool`` +:rtype: bool )"); inline constexpr bool IsVulkanExtendedCounter(GPUCounter c) { @@ -3352,7 +3353,7 @@ DOCUMENT(R"(Check whether or not this is an ARM private counter. :param GPUCounter c: The counter. :return: ``True`` if it is an ARM private counter, ``False`` if it's not. -:rtype: ``bool`` +:rtype: bool )"); inline constexpr bool IsARMCounter(GPUCounter c) { diff --git a/renderdoc/api/replay/shader_types.h b/renderdoc/api/replay/shader_types.h index fe322cb3f..237c3ae84 100644 --- a/renderdoc/api/replay/shader_types.h +++ b/renderdoc/api/replay/shader_types.h @@ -560,9 +560,10 @@ struct LineColumnInfo return false; } - DOCUMENT(R"(:return: ``True`` if this object is equal to the parameter, disregarding - :data:`disassemblyLine`. -:rtype: ``bool`` + DOCUMENT(R"( +:param LineColumnInfo o: The object to compare against. +:return: ``True`` if this object is equal to the parameter, disregarding :data:`disassemblyLine`. +:rtype: bool )"); bool SourceEqual(const LineColumnInfo &o) const { @@ -691,9 +692,11 @@ a different debug variable. )"); rdcarray sourceVars; - DOCUMENT(R"(A ``list`` of ``str`` with each function call in the current callstack at this line. + DOCUMENT(R"(The function names in the current callstack at this line. The oldest/outer function is first in the list, the newest/inner function is last. + +:type: List[str] )"); rdcarray callstack; }; @@ -781,8 +784,10 @@ If this is ``None`` then the trace is invalid. )"); ShaderDebugger *debugger = NULL; - DOCUMENT(R"(A ``list`` of :class:`LineColumnInfo` detailing which source lines each instruction -corresponds to + DOCUMENT(R"(An array of the same size as the number of instructions in the shader, with a mapping +to source lines. + +:type: List[LineColumnInfo] )"); rdcarray lineInfo; }; diff --git a/renderdoc/api/replay/structured_data.h b/renderdoc/api/replay/structured_data.h index 74ba38803..6d6ba022d 100644 --- a/renderdoc/api/replay/structured_data.h +++ b/renderdoc/api/replay/structured_data.h @@ -314,7 +314,7 @@ private: DECLARE_REFLECTION_STRUCT(SDObjectPODData); -DOCUMENT("A ``list`` of :class:`SDObject` objects"); +DOCUMENT("INTERNAL: An array of SDObject*, mapped to a pure list in python"); struct StructuredObjectList : public rdcarray { StructuredObjectList() : rdcarray() {} @@ -500,7 +500,10 @@ struct SDObject m_Parent = NULL; } - DOCUMENT("Create a deep copy of this object."); + DOCUMENT(R"( +:return: A new deep copy of this object, which the caller owns. +:rtype: SDObject +)"); SDObject *Duplicate() const { SDObject *ret = new SDObject(); @@ -535,30 +538,30 @@ recursively through children. :param SDObject obj: The object to compare against :return: A boolean indicating if the object is equal to this one. -:rtype: ``bool`` +:rtype: bool )"); - bool HasEqualValue(const SDObject *o) const + bool HasEqualValue(const SDObject *obj) const { bool ret = true; - if(data.str != o->data.str) + if(data.str != obj->data.str) { ret = false; } - else if(data.basic.u != o->data.basic.u) + else if(data.basic.u != obj->data.basic.u) { ret = false; } - else if(data.children.size() != o->data.children.size()) + else if(data.children.size() != obj->data.children.size()) { ret = false; } else { - for(size_t c = 0; c < o->data.children.size(); c++) + for(size_t c = 0; c < obj->data.children.size(); c++) { PopulateChild(c); - ret &= data.children[c]->HasEqualValue(o->GetChild(c)); + ret &= data.children[c]->HasEqualValue(obj->GetChild(c)); } } @@ -569,7 +572,7 @@ recursively through children. // python. DOCUMENT(R"(Add a new child object. -:param SDObject obj: The new child to add +:param SDObject child: The new child to add )"); inline void DuplicateAndAddChild(const SDObject *child) { @@ -583,7 +586,7 @@ recursively through children. DOCUMENT(R"(Find a child object by a given name. If no matching child is found, ``None`` is returned. -:param str name: The name to search for. +:param str childName: The name to search for. :return: A reference to the child object if found, or ``None`` if not. :rtype: SDObject )"); @@ -670,7 +673,7 @@ returned. DOCUMENT(R"(Get the number of child objects. :return: The number of children this object contains. -:rtype: ``int`` +:rtype: int )"); inline size_t NumChildren() const { return data.children.size(); } #if !defined(SWIG) @@ -821,11 +824,17 @@ returned. // these are common to both python and C++ DOCUMENT(R"(Interprets the object as a ``bool`` and returns its value. Invalid if the object is not actually a ``bool``. + +:return: The interpreted bool value. +:rtype: bool )"); inline bool AsBool() const { return data.basic.b; } // these are common to both python and C++ DOCUMENT(R"(Interprets the object as a :class:`ResourceId` and returns its value. Invalid if the object is not actually a :class:`ResourceId`. + +:return: The interpreted ID. +:rtype: ResourceId )"); inline ResourceId AsResourceId() const { return data.basic.id; } #if defined(RENDERDOC_QT_COMPAT) @@ -1047,7 +1056,17 @@ inline SDObject *makeSDObject(const rdcinflexiblestr &name, QVariant val) } #endif -DOCUMENT("Make a structured object out of a signed integer"); +DOCUMENT(R"(Make a structured object as a signed 64-bit integer. + +.. note:: + You should ensure that the value you pass in has already been truncated to the appropriate range + for the storage, as the resulting object will be undefined if the value is out of the valid range. + +:param str name: The name of the object. +:param int val: The integer which will be stored in the returned object. +:return: The new object, owner by the caller. +:rtype: SDObject +)"); inline SDObject *makeSDInt64(const rdcinflexiblestr &name, int64_t val) { SDObject *ret = new SDObject(name, "int64_t"_lit); @@ -1057,7 +1076,17 @@ inline SDObject *makeSDInt64(const rdcinflexiblestr &name, int64_t val) return ret; } -DOCUMENT("Make a structured object out of an unsigned integer"); +DOCUMENT(R"(Make a structured object as an unsigned 64-bit integer. + +.. note:: + You should ensure that the value you pass in has already been truncated to the appropriate range + for the storage, as the resulting object will be undefined if the value is out of the valid range. + +:param str name: The name of the object. +:param int val: The integer which will be stored in the returned object. +:return: The new object, owner by the caller. +:rtype: SDObject +)"); inline SDObject *makeSDUInt64(const rdcinflexiblestr &name, uint64_t val) { SDObject *ret = new SDObject(name, "uint64_t"_lit); @@ -1067,7 +1096,17 @@ inline SDObject *makeSDUInt64(const rdcinflexiblestr &name, uint64_t val) return ret; } -DOCUMENT("Make a structured object out of a integer, stored as signed 32-bits"); +DOCUMENT(R"(Make a structured object as a signed 32-bit integer. + +.. note:: + You should ensure that the value you pass in has already been truncated to the appropriate range + for the storage, as the resulting object will be undefined if the value is out of the valid range. + +:param str name: The name of the object. +:param int val: The integer which will be stored in the returned object. +:return: The new object, owner by the caller. +:rtype: SDObject +)"); inline SDObject *makeSDInt32(const rdcinflexiblestr &name, int32_t val) { SDObject *ret = new SDObject(name, "int32_t"_lit); @@ -1077,7 +1116,17 @@ inline SDObject *makeSDInt32(const rdcinflexiblestr &name, int32_t val) return ret; } -DOCUMENT("Make a structured object out of a integer, stored as unsigned 32-bits"); +DOCUMENT(R"(Make a structured object as an unsigned 32-bit integer. + +.. note:: + You should ensure that the value you pass in has already been truncated to the appropriate range + for the storage, as the resulting object will be undefined if the value is out of the valid range. + +:param str name: The name of the object. +:param int val: The integer which will be stored in the returned object. +:return: The new object, owner by the caller. +:rtype: SDObject +)"); inline SDObject *makeSDUInt32(const rdcinflexiblestr &name, uint32_t val) { SDObject *ret = new SDObject(name, "uint32_t"_lit); @@ -1087,7 +1136,17 @@ inline SDObject *makeSDUInt32(const rdcinflexiblestr &name, uint32_t val) return ret; } -DOCUMENT("Make a structured object out of a floating point value"); +DOCUMENT(R"(Make a structured object as a 32-bit float. + +.. note:: + You should ensure that the value you pass in has already been truncated to the appropriate range + for the storage, as the resulting object will be undefined if the value is out of the valid range. + +:param str name: The name of the object. +:param float val: The float which will be stored in the returned object. +:return: The new object, owner by the caller. +:rtype: SDObject +)"); inline SDObject *makeSDFloat(const rdcinflexiblestr &name, float val) { SDObject *ret = new SDObject(name, "float"_lit); @@ -1097,7 +1156,13 @@ inline SDObject *makeSDFloat(const rdcinflexiblestr &name, float val) return ret; } -DOCUMENT("Make a structured object out of a boolean value"); +DOCUMENT(R"(Make a structured object as a boolean value. + +:param str name: The name of the object. +:param bool val: The bool which will be stored in the returned object. +:return: The new object, owner by the caller. +:rtype: SDObject +)"); inline SDObject *makeSDBool(const rdcinflexiblestr &name, bool val) { SDObject *ret = new SDObject(name, "bool"_lit); @@ -1107,7 +1172,13 @@ inline SDObject *makeSDBool(const rdcinflexiblestr &name, bool val) return ret; } -DOCUMENT("Make a structured object out of a string"); +DOCUMENT(R"(Make a structured object as a string value. + +:param str name: The name of the object. +:param str val: The string which will be stored in the returned object. +:return: The new object, owner by the caller. +:rtype: SDObject +)"); inline SDObject *makeSDString(const rdcinflexiblestr &name, const rdcstr &val) { SDObject *ret = new SDObject(name, "string"_lit); @@ -1117,7 +1188,13 @@ inline SDObject *makeSDString(const rdcinflexiblestr &name, const rdcstr &val) return ret; } -DOCUMENT("Make a structured object out of a ResourceId"); +DOCUMENT(R"(Make a structured object as a ResourceId value. + +:param str name: The name of the object. +:param ResourceId val: The ID which will be stored in the returned object. +:return: The new object, owner by the caller. +:rtype: SDObject +)"); inline SDObject *makeSDResourceId(const rdcinflexiblestr &name, ResourceId val) { SDObject *ret = new SDObject(name, "ResourceId"_lit); @@ -1127,7 +1204,17 @@ inline SDObject *makeSDResourceId(const rdcinflexiblestr &name, ResourceId val) return ret; } -DOCUMENT("Make a structured object out of an enumeration value"); +DOCUMENT(R"(Make a structured object as an enum value. + +.. note:: + The enum will be stored just as an integer value, but the string name of the enumeration value can + be set with :meth:`SDObject.SetCustomString` if desired. + +:param str name: The name of the object. +:param int val: The integer value of the enum itself. +:return: The new object, owner by the caller. +:rtype: SDObject +)"); inline SDObject *makeSDEnum(const rdcinflexiblestr &name, uint32_t val) { SDObject *ret = new SDObject(name, "enum"_lit); @@ -1137,7 +1224,14 @@ inline SDObject *makeSDEnum(const rdcinflexiblestr &name, uint32_t val) return ret; } -DOCUMENT("Make an array-type structured object"); +DOCUMENT(R"(Make a structured object which is an array. + +The array will be created empty, and new members can be added using methods on :class:`SDObject`. + +:param str name: The name of the object. +:return: The new object, owner by the caller. +:rtype: SDObject +)"); inline SDObject *makeSDArray(const rdcinflexiblestr &name) { SDObject *ret = new SDObject(name, "array"_lit); @@ -1145,7 +1239,15 @@ inline SDObject *makeSDArray(const rdcinflexiblestr &name) return ret; } -DOCUMENT("Make an struct-type structured object"); +DOCUMENT(R"(Make a structured object which is a struct. + +The struct will be created empty, and new members can be added using methods on :class:`SDObject`. + +:param str name: The name of the object. +:param str structtype: The typename of the struct. +:return: The new object, owner by the caller. +:rtype: SDObject +)"); inline SDObject *makeSDStruct(const rdcinflexiblestr &name, const rdcinflexiblestr &structtype) { SDObject *ret = new SDObject(name, structtype); @@ -1218,7 +1320,10 @@ struct SDChunk : public SDObject DOCUMENT("The :class:`SDChunkMetaData` with the metadata for this chunk."); SDChunkMetaData metadata; - DOCUMENT("Create a deep copy of this chunk."); + DOCUMENT(R"( +:return: A new deep copy of this chunk, which the caller owns. +:rtype: SDChunk +)"); SDChunk *Duplicate() const { SDChunk *ret = new SDChunk(); @@ -1246,7 +1351,7 @@ protected: DECLARE_REFLECTION_STRUCT(SDChunk); -DOCUMENT("A ``list`` of :class:`SDChunk` objects"); +DOCUMENT("INTERNAL: An array of SDChunk*, mapped to a pure list in python"); struct StructuredChunkList : public rdcarray { StructuredChunkList() : rdcarray() {} @@ -1283,7 +1388,7 @@ DECLARE_REFLECTION_STRUCT(StructuredChunkList); DECLARE_REFLECTION_STRUCT(bytebuf); -DOCUMENT("A ``list`` of ``bytes`` objects"); +DOCUMENT("INTERNAL: An array of bytebuf*, mapped to a pure list of bytes in python"); struct StructuredBufferList : public rdcarray { StructuredBufferList() : rdcarray() {} @@ -1362,15 +1467,25 @@ public: delete buf; } - DOCUMENT("A ``list`` of :class:`SDChunk` objects with the chunks in order."); + DOCUMENT(R"(The chunks in the file in order. + +:type: List[SDChunk] +)"); StructuredChunkList chunks; - DOCUMENT("A ``list`` of serialised buffers stored as ``bytes`` objects"); + DOCUMENT(R"(The buffers in the file, as referenced by the chunks in :data:`chunks`. + +:type: List[bytes] +)"); StructuredBufferList buffers; DOCUMENT("The version of this structured stream, typically only used internally."); uint64_t version = 0; + DOCUMENT(R"(Swaps the contents of this file with another. + +:param SDFile other: The other file to swap with. +)"); inline void Swap(SDFile &other) { chunks.swap(other.chunks); diff --git a/renderdoc/api/replay/vk_pipestate.h b/renderdoc/api/replay/vk_pipestate.h index 22832f860..04866d5e8 100644 --- a/renderdoc/api/replay/vk_pipestate.h +++ b/renderdoc/api/replay/vk_pipestate.h @@ -201,7 +201,7 @@ conversion. DOCUMENT(R"(For samplers - check if the border color is used in this Vulkan sampler. :return: ``True`` if the border color is used, ``False`` otherwise. -:rtype: ``bool`` +:rtype: bool )"); bool UseBorder() const { diff --git a/renderdoc/core/remote_server.h b/renderdoc/core/remote_server.h index ed9cb1c79..ffbbe3b82 100644 --- a/renderdoc/core/remote_server.h +++ b/renderdoc/core/remote_server.h @@ -82,15 +82,15 @@ public: virtual rdcarray GetAvailableGPUs(); - virtual int GetSectionCount(); + virtual int32_t GetSectionCount(); - virtual int FindSectionByName(const rdcstr &name); + virtual int32_t FindSectionByName(const rdcstr &name); - virtual int FindSectionByType(SectionType sectionType); + virtual int32_t FindSectionByType(SectionType sectionType); - virtual SectionProperties GetSectionProperties(int index); + virtual SectionProperties GetSectionProperties(int32_t index); - virtual bytebuf GetSectionContents(int index); + virtual bytebuf GetSectionContents(int32_t index); virtual bool WriteSection(const SectionProperties &props, const bytebuf &contents); diff --git a/renderdoc/replay/capture_file.cpp b/renderdoc/replay/capture_file.cpp index 32fdeb59f..7d45c3208 100644 --- a/renderdoc/replay/capture_file.cpp +++ b/renderdoc/replay/capture_file.cpp @@ -158,11 +158,11 @@ public: // ICaptureAccess - int GetSectionCount(); - int FindSectionByName(const rdcstr &name); - int FindSectionByType(SectionType type); - SectionProperties GetSectionProperties(int index); - bytebuf GetSectionContents(int index); + int32_t GetSectionCount(); + int32_t FindSectionByName(const rdcstr &name); + int32_t FindSectionByType(SectionType type); + SectionProperties GetSectionProperties(int32_t index); + bytebuf GetSectionContents(int32_t index); bool WriteSection(const SectionProperties &props, const bytebuf &contents); bool HasCallstacks(); @@ -677,7 +677,7 @@ Thumbnail CaptureFile::GetThumbnail(FileType type, uint32_t maxsize) return ret; } -int CaptureFile::GetSectionCount() +int32_t CaptureFile::GetSectionCount() { if(!m_RDC) return 0; @@ -685,7 +685,7 @@ int CaptureFile::GetSectionCount() return m_RDC->NumSections(); } -int CaptureFile::FindSectionByName(const rdcstr &name) +int32_t CaptureFile::FindSectionByName(const rdcstr &name) { if(!m_RDC) return -1; @@ -693,7 +693,7 @@ int CaptureFile::FindSectionByName(const rdcstr &name) return m_RDC->SectionIndex(name); } -int CaptureFile::FindSectionByType(SectionType type) +int32_t CaptureFile::FindSectionByType(SectionType type) { if(!m_RDC) return -1; @@ -701,7 +701,7 @@ int CaptureFile::FindSectionByType(SectionType type) return m_RDC->SectionIndex(type); } -SectionProperties CaptureFile::GetSectionProperties(int index) +SectionProperties CaptureFile::GetSectionProperties(int32_t index) { if(!m_RDC || index < 0 || index >= m_RDC->NumSections()) return SectionProperties(); @@ -709,7 +709,7 @@ SectionProperties CaptureFile::GetSectionProperties(int index) return m_RDC->GetSectionProperties(index); } -bytebuf CaptureFile::GetSectionContents(int index) +bytebuf CaptureFile::GetSectionContents(int32_t index) { bytebuf ret;