开发工具调试器图形学GPU【免费下载链接】renderdocRenderDoc is a stand-alone graphics debugging tool.项目地址https://gitcode.com/gh_mirrors/re/renderdoc点击查看免费下载导读本文档是 RenderDoc 图形调试器中qrenderdocPython 模块的 UI 扩展接口API Reference深度解析。它聚焦于扩展Extension如何与 RenderDoc 的图形界面交互从扩展元数据管理ExtensionManager、Qt 控件轻量封装MiniQtHelper到各类菜单注册枚举WindowMenu / PanelMenu / ContextMenu / DialogButton的完整使用方式。读完本文你将掌握如何编写一个能在 RenderDoc 界面中注册菜单项、弹出自定义面板、与用户交互并复用renderdoc.ReplayOutput渲染画面的 UI 扩展并了解这些接口在仓库源码中的真实实现位置。该 API Reference 文档本体位于 docs/python_api/qrenderdoc/extensions.rst其中全部接口签名与详细说明由autoclass指令从 C 头文件中的DOCUMENT()注释自动提取生成本文在完整继承这些接口说明的基础上结合仓库源码对每个 API 的行为细节、默认值与注意事项做了进一步展开。高阶使用教程可参考 docs/python_api/ui_extensions.rst整体 Python API 说明见 docs/python_api/index.rst。一、扩展Extension的定位与加载方式在进入 API 细节之前先明确这些接口服务的对象。RenderDoc 的 UI 扩展本质上是 Python 模块从平台相关的固定目录加载Windows%APPDATA%\qrenderdoc\extensionsLinux~/.local/share/qrenderdoc/extensions在该路径的任意子目录中通过创建一个包含元数据的extension.json文件以及以__init__.py开头的 Python 模块即可注册一个扩展。扩展的启用/停用由扩展管理器界面控制Python 模块本身无法被卸载但文件发生变更后可以重新加载reload。加载成功后扩展定义入口函数register(version, pyrenderdoc)RenderDoc 会以版本字符串如1.23与CaptureContext作为参数调用它。通过CaptureContext.Extensions()即可取得本文的主角——ExtensionManager。更完整的扩展编写流程见 docs/python_api/ui_extensions.rst 与 docs/how/how_python_extension.rst。ExtensionManager对应源码中的IExtensionManager接口定义于 qrenderdoc/Code/Interface/Extensions.h其中对 Python 暴露的 SWIG 绑定位于 qrenderdoc/Code/pyrenderdoc/qrenderdoc.i。从源码结构看IExtensionManager被划分为“扩展管理”“UI 钩子/回调注册”“工具 UI 函数”三个功能区下文依次展开。二、ExtensionManager扩展管理与菜单注册2.1 扩展生命周期管理方法签名与说明GetInstalledExtensions()返回List[ExtensionMetadata]即所有已安装扩展的元数据列表。IsExtensionLoaded(name)参数为扩展的限定名如foo.bar返回bool表示该扩展当前是否已启用加载。GetLoadedExtensions()返回List[str]即当前已加载扩展的名称列表。LoadExtension(name)按名称启用扩展若已启用则触发重新加载。返回str成功时为空字符串失败时返回加载过程中遇到的错误文本。IsPythonDebuggerConnected()返回bool指示是否有 Python 调试器已连接。若当前构建不支持 Python 调试或调试器加载失败返回False。源码对应实现为IExtensionManager中GetInstalledExtensions/IsExtensionLoaded/GetLoadedExtensions/LoadExtension/IsPythonDebuggerConnected五个纯虚方法Extensions.h。这些方法共同支撑了扩展管理器窗口的“安装列表、启用勾选、重新加载”等交互逻辑。2.2 注册 UI 钩子三种菜单入口扩展最常见的需求是在 RenderDoc 界面中挂载自定义入口。ExtensionManager提供三类注册方法回调签名统一为ExtensionCallback(context, data)即Callable[[CaptureContext, Dict[str, Any]], None]RegisterWindowMenu(base, submenus, callback)—— 注册到主窗口菜单。baseWindowMenu枚举指定加入哪个顶层菜单。submenusList[str]菜单层级路径最后一个字符串即菜单项本身的名称至少需要一个条目当base为WindowMenu.NewMenu时至少需要两个条目。RegisterPanelMenu(base, submenus, callback)—— 注册到某个面板Panel的工具栏。basePanelMenu枚举指定加入哪个面板。submenusList[str]至少一个条目。RegisterContextMenu(base, submenus, callback)—— 注册到面板中的右键上下文菜单。baseContextMenu枚举指定哪个面板的哪类对象的右键菜单。submenusList[str]至少一个条目。三者源码均在 Extensions.h。需要注意的共用约束源码DOCUMENT注释明确说明中间层级的子菜单会按需自动创建无需逐级注册但先注册一个菜单项、再注册它的子项属于未定义行为带子项的菜单项可能无法在正确时机收到回调。此外从源码结构看MenuDisplaying相关重载被#if !defined(SWIG)隔离属于内部机制——面板菜单在显示时才动态添加条目采用近即时模式immediate-mode风格避免复杂的保留状态维护该函数不暴露给 Python。2.3 工具 UI 函数对话框与文件浏览ExtensionManager还封装了一组常用的原生对话框避免扩展自行实现MessageDialog(text, title)信息提示对话框。ErrorDialog(text, title)错误提示对话框。QuestionDialog(text, options, title) - DialogButton提问对话框options为List[DialogButton]返回用户点击的按钮。OpenFileName(caption, dir, filter) - str浏览并选择一个要打开的文件名未选择时返回空字符串。OpenDirectoryName(caption, dir) - str浏览并选择一个目录。SaveFileName(caption, dir, filter) - str浏览并选择一个要保存的文件名。GetMiniQtHelper() - MiniQtHelper取得轻量 Qt 帮助器接口详见下一章。对应源码见 Extensions.h。其中filter参数用于文件名过滤dir参数为浏览起始目录均允许留空使用默认行为。2.4 回调数据约定所有通过Register*注册的回调都接收一个Dict[str, Any]形式的data参数。源码注释说明其内容“取决于调用来源”context-dependent。C 侧的回调类型为std::functionvoid(ICaptureContext*, const rdcarrayrdcpairrdcstr, PyObject*)在启用 Qt 兼容编译时数据键值对由ExtensionCallbackDatardcarrayrdcpairrdcstr, QVariant承载见 Extensions.h。在 Python 中建议按需打印/检查data内容而不是依赖固定的键集合。三、MiniQtHelper跨构建可移植的轻量 Qt 封装MiniQtHelper源码接口IMiniQtHelperExtensions.h是 RenderDoc 为扩展提供的“迷你 Qt 工具”。设计动机很直接PySide2 并非在所有 RenderDoc 构建中都可用因此该帮助器通过 RenderDoc 自身的 Python 绑定暴露 Qt 的一个小子集让扩展能够在任何RenderDoc 构建上完成基本的数据输入与展示 UI。源码注释同时强调两点其意图不是允许完全灵活地构建 Qt 面板而是提供基础 UI 搭建能力当 PySide2 可用时返回的控件句柄本身就是 PySide2 widget因此可以在此基础上用完整 PySide2 进一步定制。3.1 线程与生命周期基础InvokeOntoUIThread(callback)把回调调度到 UI 线程执行。所有控件访问必须发生在 UI 线程因此当工作在 replay 线程完成后用此函数安全地异步切回 UI 线程在 UI 线程调用该函数会同步立即执行回调。回调签名UIInvokeCallback为Callable[[], None]不传参数回调需自行维护上下文。CreateToplevelWidget(windowTitle, closedNone) - QWidget创建顶级窗口控件不会立即显示需配合ShowWidgetAsDialog或CaptureContext.AddDockWindow展示。closed为可选的WidgetCallback在用户关闭该窗口时被调用关闭会隐式删除该控件及其全部子控件此后持有的句柄失效。CloseToplevelWidget(widget)模拟用户点击关闭会触发closed回调仅适用于顶级控件。DestroyWidget(widget)销毁控件递归销毁所有子控件。被销毁后句柄不可再用若销毁的是顶级窗口会将其关闭。用户关闭顶级窗口是另一种使控件失效的途径。3.2 控件层级查询SetWidgetName(widget, name)/GetWidgetName(widget)设置/读取内部名称不显示在界面上供FindChildByName定位。名称是可选的重复名称会使搜索产生歧义。GetWidgetType(widget) - str返回 Qt 类型名字符串仅用于调试——同一类型控件的名字可能随版本变化。FindChildByName(parent, name) - QWidget按内部名称在层级中查找子控件未找到返回None。GetParent(widget) - QWidget返回父控件注意若控件已被停靠dock到别处返回的父控件可能并非通过帮助器创建修改它可能影响 RenderDoc 自身 UI。未挂接父级或本身就是顶级窗口时返回None。GetNumChildren(widget) - int/GetChild(parent, index) - QWidget子控件数量与按索引取子控件越界返回None主要对布局类控件有用。3.3 对话框模式ShowWidgetAsDialog(widget) - bool把顶级控件作为阻塞式模态对话框显示适合向用户索取特定信息。对话框仅在用户显式关闭或你在某个控件回调中调用CloseCurrentDialog时关闭。CloseCurrentDialog(success)关闭当前模态对话框。successTrue表示用户点了 OK/Accept 类按钮该参数只影响ShowWidgetAsDialog的返回值便于区分确定/取消无需额外全局状态。3.4 布局容器方法说明CreateHorizontalContainer()水平布局控件子项横向排列。CreateVerticalContainer()垂直布局控件子项纵向排列。CreateGridContainer()网格布局控件子项按网格排列。CreateSpacer(horizontal)空白占位控件吞掉空闲空间使其他非贪婪控件最小化horizontalTrue消耗水平空间。ClearContainedWidgets(parent)移除父控件下所有子控件并隐藏子控件仍有效可重新挂接。AddWidget(parent, child)在水平/垂直有序布局末尾追加子控件父控件不是有序布局时静默无效。InsertWidget(parent, index, child)在指定索引插入索引越界会被钳制负数等价于 0超出则追加。AddGridWidget(parent, row, column, child, rowSpan, columnSpan)向网格布局添加子控件支持跨行跨列父控件不是网格布局时静默无效。SetLayoutSpacing(layout, spacing)设置布局内部项间距像素非布局控件无效。SetLayoutMargins(layout, horizontal, vertical)设置布局外部边距horizontal为左右边距、vertical为上下边距。控件尺寸遵循 Qt 默认逻辑部分控件只占内容大小部分“贪婪”控件均分剩余空间网格布局不会破坏网格约束。3.5 通用控件属性文本SetWidgetText(widget, text)按控件类型解释文本文本框/标签直接设置文本复选框/单选框在旁附加文本GetWidgetText(widget)读取AppendText(widget, text)追加文本对多行编辑框体验更好并自动滚动、移动光标到末尾。滚动ScrollToTop(widget)/ScrollToBottom(widget)操作垂直滚动条无滚动条的控件静默无效。字体SetWidgetFont(widget, font, fontSize, bold, italic)font可传_default或_fixed分别选择用户设置的默认字体/等宽字体空字符串表示保持字体族不变fontSize0表示保持字号不变。启用态SetWidgetEnabled(widget, enabled)/IsWidgetEnabled(widget)禁用后控件对用户只读但程序仍可修改。可见性SetWidgetVisible(widget, visible)/IsWidgetVisible(widget)可见性查询是递归的——父级不可见时子控件也判定为不可见。3.6 具体控件工厂方法说明CreateGroupBox(collapsible)分组框collapsibleTrue时标题带折叠开关。建议立即添加一个布局类子控件以定制内容排列默认垂直布局。CreateButton(pressedNone)普通按钮pressed为点击回调WidgetCallback。CreateLabel()只读标签默认为空文本用SetWidgetText设置。SetLabelImage(widget, data, width, height, alpha)为标签设置图片数据必须为 RGB(A) 格式每像素首字节为 R标签会固定尺寸按 100% 显示传入空数据可还原为文本标签。非标签控件无效。CreateCheckbox(changedNone)/CreateRadiobox(changedNone)复选框/单选框创建时均未勾选同组兄弟单选框最多一个被勾选需要默认勾选时用SetWidgetChecked。changed为切换回调。SetWidgetChecked(widget, checked)/IsWidgetChecked(widget)勾选状态读写仅对复选框、单选框、分组框有效其他类型IsWidgetChecked返回False。CreateSpinbox(decimalPlaces, step)数字微调框decimalPlaces0时为整数微调框此时 step 应设为 1.0默认值域 0.0~100.0可用SetSpinboxBounds(spinbox, minVal, maxVal)修改越界输入会被钳制。SetSpinboxValue/GetSpinboxValue读写当前值非微调框读值返回0.0。CreateTextBox(singleLine, changedNone)文本框singleLineFalse时为多行文本changed在文本变化时回调。CreateComboBox(editable, changedNone)下拉组合框editableTrue时允许用户输入任意文本。创建时无预置选项用SetComboOptions(combo, options)设置GetComboCount返回选项数非组合框返回 0SelectComboOption(combo, option)选择选项未知选项静默无效。changed在选择或编辑文本时均会被调用。CreateProgressBar(horizontal)进度条默认值域 0~100。SetProgressBarRange(pbar, minimum, maximum)设置值域若maximum minimum则以 minimum 为最大值当前值越界会重置进度条(0, 0)表示不确定indeterminate状态。ResetProgressBar回卷指示器并隐藏标签主题相关想保留标签可改调SetProgressBarValue(pbar, 0)。另有SetProgressBarValue/UpdateProgressBarValue相对增量/GetProgressBarValue/GetProgressBarMinimum/GetProgressBarMaximum。3.7 与 ReplayOutput 的集成渲染画面控件MiniQtHelper 提供了一条在自定义面板内渲染捕获画面的官方路径包含四个配套方法CreateOutputRenderingWidget()创建适合用renderdoc.ReplayOutput渲染的控件。它按需处理重绘、必要时重建内部显示控件。GetWidgetWindowingData(widget) - renderdoc.WindowingData取窗口数据用于ReplayController.CreateOutput。必须尽量靠近CreateOutput调用因为窗口数据并非永久有效且只有当你确实要创建 output 时才取否则控件会进入未定义状态。此函数必须在主 UI 线程调用传入非渲染控件会返回无效数据。SetWidgetReplayOutput(widget, output)设置当前 output传None复位为默认背景关闭捕获时控件会自动解除 output无需手动处理。SetWidgetBackgroundColor(widget, red, green, blue)设置无 output 时的背景色分量范围 0.0~1.0传负分量值则恢复默认棋盘格背景这也是创建时的默认行为。配合CaptureContext.AddDockWindow与ReplayController.CreateOutput扩展即可构建出具备实时画面预览的自定义面板。四、Helpers扩展相关的数据结构与枚举4.1 ExtensionMetadata扩展元数据ExtensionMetadata源码结构体见 Extensions.h描述一个已安装扩展由GetInstalledExtensions()返回。字段如下字段类型含义extensionAPIint该扩展所针对的扩展 API 版本。filePathstr该包在磁盘上的位置。packagestr该扩展的 Python 包名如foo.bar。namestr简短友好的扩展名。versionstr扩展版本。authorstr扩展作者可附带邮箱联系方式。extensionURLstr扩展获取来源的 URL。descriptionstr扩展功能的更长描述。hasChangesbool扩展自上次加载以来是否在磁盘上发生变化扩展未加载时恒为False。failedLoadbool扩展是否加载失败未加载时恒为False。其中hasChanges与failedLoad两个标志驱动了状态栏“文件已变更点击重新加载”的提示逻辑。4.2 WindowMenu主窗口菜单位置指定把菜单项加入主窗口的哪个菜单Extensions.h值含义Unknown未知/无效窗口。File位于 Open/Save/Close 捕获与 Import/Export 之间的区域。Window位于菜单末尾的新区域。Tools位于 Settings 上方的新区域。NewMenu作为根级菜单位于 Tools 与 Help 之间。Help位于错误报告项之后。4.3 PanelMenu面板菜单位置指定把菜单项加入哪个面板的工具栏Extensions.h值含义Unknown未知/无效面板。EventBrowser事件浏览器EventBrowser。PipelineStateViewer管线状态查看器PipelineStateViewer。MeshPreview网格预览类型的BufferViewer。TextureViewer纹理查看器TextureViewer。BufferViewer任何非网格预览的BufferViewer。4.4 ContextMenu右键菜单位置指定把菜单项加入哪个面板中哪类对象的右键菜单Extensions.h值含义Unknown未知/无效上下文菜单。EventBrowser_Event事件浏览器中的事件条目。MeshPreview_Vertex网格预览中所有顶点。MeshPreview_VSInVertex网格预览中的 VS 输入顶点。MeshPreview_VSOutVertex网格预览中的 VS 输出。MeshPreview_GSOutVertex网格预览中的 GS/Tess 输出。MeshPreview_TaskOutVertex网格预览中的任务着色器输出。MeshPreview_MeshOutVertex网格预览中的网格着色器输出。TextureViewer_Thumbnail纹理查看器中的所有缩略图。TextureViewer_InputThumbnail纹理查看器中的输入缩略图。TextureViewer_OutputThumbnail纹理查看器中的输出缩略图。4.5 DialogButton对话框按钮集合DialogButtonExtensions.h用于QuestionDialog的按钮组合其枚举值与QMessageBox::StandardButton保持同步源码注释明确要求二者同步。成员包括OK、Save、SaveAll、Open、Yes、YesToAll、No、NoToAll、Abort、Retry、Ignore、Close、Cancel、Discard、Help、Apply、Reset、RestoreDefaults并定义了BITMASK_OPERATORS支持按位组合。五、回调签名速查回调签名说明ExtensionCallbackCallable[[CaptureContext, Dict[str, Any]], None]RegisterWindowMenu/RegisterPanelMenu/RegisterContextMenu的回调data为字符串键字典内容取决于触发场景。WidgetCallbackCallable[[CaptureContext, QWidget, str], None]控件回调创建控件时可注册text字段可选、可能为空视事件而定context与widget始终有效。UIInvokeCallbackCallable[[], None]通过InvokeOntoUIThread调度到 UI 线程的回调不传参数回调自行保存所需状态。六、综合实战从注册菜单到弹出自定义面板仓库中 docs/python_api/ui_extensions.py 提供了一个完整的“寻宝游戏”示例对应教程见 docs/python_api/ui_extensions.rst几乎用到了上文所有核心 API是理解整套机制的理想范本。下面拆解其关键链路1. 入口注册register函数def register(version, pyrenderdoc: qrd.CaptureContext): print(fTutorial extension registered in RenderDoc {version}) pyrenderdoc.Extensions().RegisterPanelMenu( qrd.PanelMenu.EventBrowser, [Tutorial, Scavenger Hunt], open_window )扩展被加载/重新加载时register(version, pyrenderdoc)被调用随后通过pyrenderdoc.Extensions()取得ExtensionManager用RegisterPanelMenu把菜单项挂到事件浏览器的PanelMenu.EventBrowser位置子菜单路径[Tutorial, Scavenger Hunt]表示在Tutorial子菜单下创建Scavenger Hunt项点击后回调open_window。2. 构建窗口open_window回调def open_window(pyrenderdoc: qrd.CaptureContext, data): mqt pyrenderdoc.Extensions().GetMiniQtHelper() top mqt.CreateToplevelWidget(Scavenger Hunt) group mqt.CreateGroupBox(False) mqt.SetWidgetText(group, Exciting scavenger hunt!) label mqt.CreateLabel() mqt.SetWidgetText(label, Guess the biggest draw!) eid, size find_largest_draw(0, pyrenderdoc.CurRootActions()) def do_guess(pyrenderdoc, widget, text): if pyrenderdoc.CurEvent() eid: msg You found it! elif pyrenderdoc.CurEvent() eid: msg The largest draw is later in the capture... else: msg The largest draw is earlier in the capture... mqt.SetWidgetText(label, fGuess the biggest draw!\n\n{msg}) button mqt.CreateButton(do_guess) mqt.SetWidgetText(button, Guess) mqt.AddWidget(top, group) mqt.AddWidget(group, label) mqt.AddWidget(group, button) pyrenderdoc.AddDockWindow( top, qrd.DockReference.TopOf, pyrenderdoc.GetEventBrowser().Widget(), 0.2 )这里演示了GetMiniQtHelper()取帮助器、CreateToplevelWidget建顶级窗口、CreateGroupBox/CreateLabel/CreateButton建控件、SetWidgetText设文本、AddWidget组装层级、CreateButton注册WidgetCallback签名(context, widget, text)更新标签最后用CaptureContext.AddDockWindow把窗口停靠到事件浏览器上方。教程特别提示任意控件都能作为顶级停靠面板加入但推荐使用显式的顶级控件以便利用其关闭回调。另一个更丰富的纯控件示例见 docs/python_api/examples/miniqt_ui.py展示了CreateHorizontalContainer、CreateCheckbox、CreateProgressBarSetProgressBarRange、SetWidgetFont、SetWidgetEnabled等的组合用法含“只读文本框”演示。七、深入源码接口背后的实现线索对于希望理解底层机制的读者仓库中值得继续追踪的实现点包括接口定义IExtensionManager与IMiniQtHelper完整定义于 qrenderdoc/Code/Interface/Extensions.h每个方法的DOCUMENT()注释即 API 文档的权威来源SWIG 绑定入口见 qrenderdoc/Code/pyrenderdoc/qrenderdoc.i。获取方式CaptureContext.Extensions()返回IExtensionManager声明于 qrenderdoc/Code/Interface/QRDInterface.h。Qt 兼容层在启用RENDERDOC_QT_COMPAT的构建中回调数据使用ExtensionCallbackData rdcarrayrdcpairrdcstr, QVariantExtensions.h与 Python 侧Dict[str, Any]的语义一一对应。内部机制IExtensionManager::MenuDisplaying的重载位于#if !defined(SWIG)保护区内Extensions.h负责面板菜单显示时动态注入菜单项属于不暴露给 Python 的内部实现这也解释了为何RegisterPanelMenu注册的条目能出现在动态构建的工具栏中。扩展加载流程extension.json元数据与__init__.py的加载/重新加载逻辑可结合 docs/how/how_python_extension.rst 中关于扩展注册的描述交叉印证。结语qrenderdoc的 UI 扩展体系由ExtensionManager管理与注册入口、MiniQtHelper可移植的轻量 UI 搭建、以及ExtensionMetadata/WindowMenu/PanelMenu/ContextMenu/DialogButton等辅助类型构成。即使不依赖 PySide2也能借此在任意 RenderDoc 构建上实现菜单挂载、模态对话框、表单控件、进度反馈乃至实时渲染画面嵌入。建议在编写扩展时优先从仓库的 docs/python_api/qrenderdoc/extensions.rst 与教程 docs/python_api/ui_extensions.rst 出发再结合本仓库源码中的接口注释确认每个参数的默认值与边界行为即可快速构建出稳定、可移植的 UI 扩展。赞分享开发工具调试器图形学GPU【免费下载链接】renderdocRenderDoc is a stand-alone graphics debugging tool.项目地址https://gitcode.com/gh_mirrors/re/renderdoc点击查看免费下载相关推荐RenderDoc qrenderdoc 模块 API 全解析CaptureContext、ReplayManager 与 UI 扩展开发指南RenderDoc qrenderdoc 模块 API 全解析CaptureContext、ReplayManager 与 UI 扩展开发指南 qrender开发工具调试器图形学GPUOHIF ExtensionManager 完全指南扩展注册、模块访问与数据源管理OHIF ExtensionManager 完全指南扩展注册、模块访问与数据源管理 导读 本文围绕 OHIF 平台核心类 ExtensionManager 展医疗健康前端音视频RenderDoc qrenderdoc Windows API 参考通过 Python 扩展驱动全部 UI 面板RenderDoc qrenderdoc Windows API 参考通过 Python 扩展驱动全部 UI 面板 导读 qrenderdoc.windows开发工具调试器图形学GPU创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考