开发工具调试器图形学GPU【免费下载链接】renderdocRenderDoc is a stand-alone graphics debugging tool.项目地址https://gitcode.com/gh_mirrors/re/renderdoc点击查看免费下载导读本文基于 RenderDoc 官方文档中的 Event IDs 章节深入讲解捕获capture中事件 IDEID的分配规则、Action 的组织方式以及如何通过APIEvent.chunkIndex交叉引用结构化数据Structured Data来还原每个 API 调用的完整参数。读完本文你将掌握 EID 的编号规律与边界情况、利用GetRootActions/CurRootActions遍历帧内 Action 树的方法以及编写 Python 扩展时从事件 ID 定位到真实调用参数的完整技术路径。什么是 Event IDEID在 RenderDoc 中捕获文件内的每一个事件event都会被分配一个Event ID简称EID。它本质上是一个简单的整数捕获中第一个真实事件的 EID 为1EID 0代表第一个事件发生之前的那个虚拟时间点常被用作帧起点或尚未执行任何事件的状态引用。EID 是 RenderDoc 回放replay与浏览的核心参考坐标。在 renderdoc/api/replay/data_types.h 中APIEvent.eventId的官方文档明确指出This is a 1-based count of API events in the capture. The eventId is used as a reference point in many places in the API to represent where in the capture the current state is, and to perform analysis in reference to the state at a particular point in the frame.也就是说eventId是一个从 1 开始计数的 API 事件序号API 中很多地方用它来表示当前状态所处的位置并据此对帧内特定时间点的状态做分析。EID 与函数调用并非严格一一对应EID通常与应用程序发起的函数调用一一对应但这一点并不保证成立。源码中对eventId的文档renderdoc/api/replay/data_types.h专门说明了例外情况Also eventIds may not correspond directly to an actual function call - sometimes a function such as a multi action indirect will be one function call that expands to multiple events to allow inspection of results part way through the multi action.典型例子是Multi-Draw 或 Indirect 执行一次 CPU 侧的 API 调用在 GPU 上可能展开为多个事件因此会被分配多个 EID以便用户能在多动作执行到中间某个阶段时检查结果。EID 的编号规律与两个例外正常情况下EID连续且递增从 1 开始依次编号。但存在两种例外Fake Marker虚拟标记当捕获中没有用户标记区域marker region且开启了自动添加 fake marker 的选项时这些虚拟标记会被赋予较高的 EID。因此你可能会看到某个 EID 为 100 的标记区域其子事件的 EID 却只有 5~10 这样更小的数字——即 EID 不再严格单调递增。多动作展开如上文所述一次调用展开为多个事件时事件数量会多于调用次数。ReplayController.AddFakeMarkers()的接口文档renderdoc/api/replay/renderdoc_replay.h对 fake marker 的 EID 行为给出了权威说明The event IDs for fake marker pushes and pops will not be contiguous with the surrounding actions and will be set to values above the last real event in the capture. This also means they break the typical rules that event IDs always increase. Its recommended that these events are not referenced directly in other calls such as SetFrameEvent, and fake markers should be used sparingly at all compared to proper application-provided markers.实践建议如果你的分析逻辑对 EID 的单调性与连续性有强依赖例如用 EID 做区间判断、排序应避免调用AddFakeMarkers()同时不要直接以 fake marker 的 EID 作为SetFrameEvent等调用的参数。在 API 侧ActionDescription.IsFakeMarker()renderdoc/api/replay/data_types.h可以帮你识别某个 action 是否为 fake marker——其判定条件是events.size() 1 events[0].chunkIndex APIEvent::NoChunk即该 action 仅含一个事件且没有对应的 chunk 索引。当前事件Current EventEID 的快照锚点EID 之所以重要是因为 RenderDoc 中几乎所有可查看的状态纹理、缓冲、管线状态等都是某个单一事件执行完毕后那一刻的 GPU 状态快照。这个锚点被称为当前事件current event即 docs/python_api/in_depth/curevent.rst 所描述的The current event is the event ID where this point sits. All things that follow including resource contents like buffers and textures, as well as pipeline state and anything else will be frozen exactly at that point.这里需要区分两个概念选中事件selected event你在 UI 中实际点选的 marker 区域本身它是包含众多子事件的根事件其 EID通常小于它的子事件当前事件current event真正用于取状态快照的有效事件。当选中一个 marker 区域时有效事件位于该区域内所有子事件执行完之后——即选中一个包含多次绘制draw的区域看到的渲染结果等价于直接选中该区域最后一个子事件时的状态。这套选中 vs 当前的双轨机制是理解 RenderDoc 事件浏览器的关键详见 docs/python_api/in_depth/curevent.rst。Action组织事件浏览的核心结构虽然事件是粒度为单次调用的概念但 RenderDoc 实际以Action为骨架来组织整个帧。官方文档docs/python_api/in_depth/event_ids.rst对 Action 的界定是Actions include any event which will execute shader code such as a draw or dispatch, but also includes anything that can modify memory or have visible side-effects like copies and clears. Although debug markers do not modify anything and have no semantic impact they are considered actions so that they can form the hierarchy that organises the actions in a capture.也就是说Action 覆盖执行着色器代码的事件draw绘制、dispatch计算分发、dispatch rays光线追踪分发等有可见副作用的事件copy拷贝、clear清除、resolve解析、blit、gen-mips 等调试标记debug marker本身不修改任何东西也没有语义影响但被当作 Action 以便构成组织整个捕获的层级树。ActionDescription结构的类型注释renderdoc/api/replay/data_types.h给出了同样的定义任何可能对应用可见内存产生刻意可见副作用的 GPU 事件以及提供用户生成注释的 marker都属于 action。获取 Action 列表可以通过两个 API 获取捕获中根层级root的 Action 列表API适用场景源码位置ReplayController.GetRootActions()在回放控制器上下文中获取renderdoc/api/replay/renderdoc_replay.hCaptureContext.CurRootActions()在 qrenderdoc UI 扩展Python 插件中获取当前捕获qrenderdoc/Code/Interface/QRDInterface.h每个根 Action 还可以有子 Actionchildren常见的子结构包括 marker 区域和 Multi-Draw 调用。遍历时利用parent、previousAction、nextAction三个指针renderdoc/api/replay/data_types.h可以方便地在 Action 树中上下游导航。测试用例 util/test/tests/D3D11/D3D11_Empty_Capture.py 展示了一个最简使用模式actions self.controller.GetRootActions() assert len(actions) 1 assert End in actions[0].customName assert actions[0].eventId 1对于空捕获第一个根 Action 的eventId就是 1——这与首个真实事件 EID 为 1的规则完全一致可用于验证 EID 编号规则。ActionDescription 的关键字段ActionDescriptionrenderdoc/api/replay/data_types.h携带了描述一次动作所需的几乎所有信息其字段按用途可分为几类身份与命名字段含义eventId真正产生该 action 的事件 IDactionId该 action 相对于其他 action 的 1-based 序号customName自定义名称对 marker 是用户提供的字符串对其他 action 通常为空可用结构化数据生成flagsActionFlags位标志描述 action 的类型与属性绘制/分发参数以下字段未使用时为 0字段含义numIndices统一字段对索引绘制是索引数量对非索引绘制是顶点数量numInstances实例数量baseVertex索引绘制中取索引后附加到每个索引的偏移indexOffset索引绘制中从索引缓冲取的首个索引vertexOffset非索引绘制中查找顶点输入前的偏移instanceOffset实例化绘制中查找实例化顶点输入前的偏移drawIndex多动作如 indirect中该 action 的序号非多动作时为 0dispatchDimension/dispatchThreadsDimension/dispatchBase分发的三维工作组数、每工作组线程数、工作组 ID 基础偏移拷贝/解析/Blit 参数字段含义copySource/copySourceSubresource源对象 ResourceId 与子资源copyDestination/copyDestinationSubresource目标对象 ResourceId 与子资源层级关系字段含义parent父 action无则为NonepreviousAction/nextAction帧内前一个 / 后一个 actionchildren子 action 列表marker 区域或多动作events该 action 自上一个 action 以来累积的事件列表outputs/depthOut颜色输出与深度输出的 ResourceId可用于把 action 粗略分桶为相似的 pass其中特别值得注意的是numIndices的统一语义——官方文档renderdoc/api/replay/data_types.h明确说明它同时表示索引绘制中的索引数和非索引绘制中的顶点数这是 RenderDoc 为简化 API 使用而做的字段合并。ActionFlags一眼识别 action 类型ActionDescription.flags的类型是ActionFlagsrenderdoc/api/replay/replay_enums.h它把类型与修饰标志编码进同一个位掩码类型位Clear、Drawcall、Dispatch、MeshDispatch、CmdList、SetMarker、PushMarker、PopMarker、Present、MultiAction、Copy、Resolve、GenMips、PassBoundary、DispatchRay、BuildAccStruct标志位Indexed索引绘制、Instanced实例化、Auto、Indirect间接执行、ClearColor、ClearDepthStencil、BeginPass、EndPass、CommandBufferBoundary命令缓冲边界虚拟标记。例如判断一个 action 是否为绘制调用可检查flags ActionFlags.Drawcall判断是否为间接绘制可检查Indirect位Multi-Draw 展开出的每个子 action 则带有MultiAction类型位。APIEvent轻量事件表示与 API 参数还原APIEvent 的字段每个事件对应一个APIEvent结构renderdoc/api/replay/data_types.h它是一个轻量级表示字段含义eventId该 API 事件的 EIDchunkIndex该函数调用在结构化文件中的 chunk 索引不可用时为NoChunkfileOffset数据流中该事件发生的字节偏移仅用于相对比较并非磁盘文件中的字面字节数annotations与该事件关联的可选注释集合未使用时为NoneAPIEvent的比较运算符、都基于eventId实现renderdoc/api/replay/data_types.h这再次印证了 EID 是事件身份的唯一坐标。关键点APIEvent 不包含调用参数APIEvent中没有函数调用的名称也没有参数内容——它只是一个轻量指针。要拿到调用参数必须交叉引用结构化数据取APIEvent.chunkIndex只要不是NoChunk即~0U见 renderdoc/api/replay/data_types.h用该索引在SDFile.chunks列表中定位对应的 chunkdocs/python_api/in_depth/structured_data.rst 说明每个 chunk 对应一次自包含的序列化函数调用从GetStructuredFile()/GetStructuredFile获取结构化文件chunk 的子节点通常对应调用的输入参数。获取结构化文件的两个 APIReplayController.GetStructuredFile()renderdoc/api/replay/renderdoc_replay.hCaptureContext.GetStructuredFile()qrenderdoc UI 扩展一个典型的 Python 交叉引用流程如下# 假设已获得 ReplayController 实例 controller 与某个事件 event sdfile controller.GetStructuredFile() chunk sdfile.chunks[event.chunkIndex] # chunk.name 即函数调用名如 vkCmdDraw子节点通常对应参数 name chunk.name () print(name) for child in chunk.children: print(child.name, child.data)ActionDescription.GetName()renderdoc/api/replay/data_types.h正是这一机制的官方实现它优先返回customName否则取events中最后一个事件即产生该 action 的那个事件的chunkIndex到结构化数据中查 chunk 名并拼接()作为 action 名称。关于结构化数据的两个重要注意事项序列化捕获数据的结构化表示是未文档化的docs/python_api/in_depth/structured_data.rst 明确警告——序列化捕获的 structured data 完全未文档化且可能变化一般会与 API 函数调用的预期接近但不保证不应将其视为稳定契约。chunk 子节点不一定是参数每个 chunk 可视为一个无名结构体对 API 事件而言子节点通常对应输入参数但该规则同样不保证有些子节点可能是返回值或 RenderDoc 内部数据。建议利用SDTypeFlags判断对象是否应显示或属于隐藏/内部数据。此外APIEvent.chunkIndex NoChunk的情况只会在捕获加载后新增的 fake marker 上出现见 renderdoc/api/replay/data_types.h这也是IsFakeMarker()判定逻辑的由来。实战从事件浏览到参数还原的完整路径综合以上内容在 RenderDoc 中分析一次捕获的标准流程可以概括为获取 Action 树通过GetRootActions()回放环境或CurRootActions()qrenderdoc 扩展拿到根 Action 列表遍历与筛选利用flagsActionFlags筛选绘制/分发/拷贝等目标类型利用children、parent、previousAction在层级中导航定位事件从目标 action 的events列表该 action 累积的、自上一个 action 以来的所有事件中取出感兴趣的APIEvent其中events的最后一个元素对应产生该 action 本身的事件状态快照需要查看某一时刻的缓冲、纹理或管线状态时用 EID 设置当前事件如SetFrameEvent注意对 fake marker 的 EID 应避免直接引用还原调用参数用APIEvent.chunkIndex在GetStructuredFile().chunks中定位 chunk解析出函数名与参数必要时结合SDTypeFlags过滤内部数据。测试套件中的大量用例如 util/test/tests/D3D11/D3D11_AMD_Shader_Extensions.py、util/test/tests/D3D11/D3D11_Counters.py都遵循先GetRootActions找 action再以action.eventId设置事件这一模式可作为编写扩展或测试时的参考模板。总结Event ID 是 RenderDoc 全部分析能力的坐标轴它标定状态快照的锚点current event、组织浏览的骨架action 树并借助chunkIndex打通从轻量事件到完整调用参数的数据通路。理解 EID 的编号规则从 1 起、通常连续递增与两个例外fake marker 的高 EID 区间、多动作的 1 对多展开是在编写自动化分析与 UI 扩展时避免踩坑的前提。进一步阅读可参考 docs/python_api/in_depth/curevent.rst当前事件与选中事件与 docs/python_api/in_depth/structured_data.rst结构化数据系统或查看 docs/python_api/in_depth/replay_controller.rst 了解回放控制器的完整能力。赞分享开发工具调试器图形学GPU【免费下载链接】renderdocRenderDoc is a stand-alone graphics debugging tool.项目地址https://gitcode.com/gh_mirrors/re/renderdoc点击查看免费下载相关推荐Axure RP 中文语言包安装完整指南免费汉化 11/10/9 三步搞定Axure RP 中文语言包安装完整指南免费汉化 11/10/9 三步搞定 产品、设计、原型这几件事最卡手的往往不是工具本身而是工具界面上那些看得懂字母、Btrfs文件ID映射WinBtrfs 128位inode支持详解Btrfs文件ID映射WinBtrfs 128位inode支持详解 引言Windows下的Btrfs文件标识挑战 你是否在Windows系统中遇到过Btrf驱动开发存储Anthropic Cybersecurity Skills 的 MITRE F3 映射mitre_f3 前置元数据模式、ID 约定与验证机制Anthropic Cybersecurity Skills 的 MITRE F3 映射mitre_f3 前置元数据模式、ID 约定与验证机制 本篇技术文章以网络安全AI 技能/插件渗透测试红蓝对抗创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考