开发工具调试器图形学GPU【免费下载链接】renderdocRenderDoc is a stand-alone graphics debugging tool.项目地址https://gitcode.com/gh_mirrors/re/renderdoc点击查看免费下载结构化数据Structured Data是 RenderDoc 内部用于表示任意类型数据包括精确到字节大小的基础类型的通用树形系统。它既承担了序列化捕获数据可读化表示的重任也支撑着配置系统GetConfigSetting与命令/对象注释APIEvent.annotations等上层功能。读完本文你将理解SDObject/SDFile的完整对象模型与类型体系掌握从 Python 中遍历、查找、修改结构化数据的全部方法与关键实践并学会如何将 API 事件与序列化 chunk 一一对应。结构化数据系统是什么、用在哪里在 RenderDoc 中结构化数据是一套独立于图形 API 的数据表示层。它在以下场景中被广泛复用序列化数据的可读形式当捕获文件.rdc加载后其序列化内容会被解码为一棵可读的结构化数据树根为SDFile供脚本分析与 UI 显示。配置系统通过renderdoc.GetConfigSetting读取的配置项本质上也是以结构化对象形式存在。注释Annotations系统应用通过SetCommandAnnotation/SetObjectAnnotation写入的注释最终以SDObject形式挂载在APIEvent.annotations逐命令与ResourceDescription.annotations逐资源上。这套系统的核心头文件是 structured_data.h所有相关类型SDBasic、SDType、SDObject、SDChunk、SDFile等均定义于此事件与 chunk 的关联则定义在 data_types.h 的APIEvent结构中。树形对象模型SDObject数据以树结构表示树的每个节点都是一个SDObject。SDObject包含三个核心成员见 structured_data.hname对象名称strtype对象类型描述SDType见下文data对象内容SDObjectData。一个SDObject可以是叶节点仅含单个值也可以是带子节点的节点结构体StructSDObject的每个成员对应一个子节点子节点各自有不同的名称数组Array每个数组元素对应一个子节点子节点类型相同仅以下标区分。每个对象拥有自己的子节点对象析构时子节点会被一并删除需要独立副本时应使用Duplicate()进行深拷贝。对象之间通过GetParent()可以回溯到父节点。基础类型枚举 SDBasicSDObject.type.basetype决定对象的基本类型其取值由SDBasic枚举定义共 14 种SDBasic 值含义Chunk特殊类型表示一个 chunk可当作Struct处理见SDChunkStruct复合类型含若干类型不同、各有名称的子节点可能为空Array复合类型含若干类型相同、仅以下标区分的子节点可能为空Null表示该位置本可有对象但当前缺席与SDTypeFlags.Nullable配合Buffer不透明字节缓冲String字符串UTF-8 编码Enum枚举值——以整数存储但有一组命名的可能取值UnsignedInteger/SignedInteger无符号 / 有符号整数Float浮点数值Boolean布尔真/假值Character单字节字符宽字符/多字节字符不支持会被存为 UTF-8 多字节字符串Resource一个ResourceId等效于并按8 字节无符号整数存储但特指捕获中资源的唯一 IDGPUAddress一个 GPU 指针等效于 8 字节无符号整数但特指捕获中资源的地址类型描述 SDType 与 byteSizeSDType描述类型的名称与属性包含四个成员name类型名称如uint32_t、VkImage对应原始序列化类型名basetype上述SDBasic类别flagsSDTypeFlags位标志见下byteSize该类型实例占用的字节数。byteSize的取值规则需要注意对整个 chunk 有效等于整个 chunk 的大小对任意大小的 buffer 有效对整数、浮点等基础类型有效给出类型的尺寸/精度对 struct、array 等变长类型则为 0。类型标志 SDTypeFlagsSDTypeFlags是作用于类型的位标志在 Python 中可组合Flag 枚举。常见标志如下标志含义NoFlags无特殊属性HasCustomString该类型有自定义字符串如枚举的字符串形式或底层非字符串但希望以字符串展示的不透明类型Hidden视为实现细节通常不应展示给用户Nullable可空类型可能被移除并替换为Null类型NullString表示这是一个为NULL的 C 字符串区别于空字符串FixedArray表示这是定长真实数组而非复杂容器或指针 长度Union表示结构体以 union 存储所有子节点共享同一块内存由外部标志指示哪个成员有效Important表示该对象重要/显著用于生成 chunk 的摘要单行视图时只纳入重要子节点该属性可递归ImportantChildren表示只处理重要子节点出现在没有重要子节点的对象上时明确表示摘要中不显示任何参数HiddenChildren表示部分子节点被标记为隐藏在子节点数量本身很重要时需要留意OffsetOrSize表示该类型用作字节偏移或字节大小用于控制 UI 展示时的格式化模式以Hidden为例判定一个对象是否应展示给用户应依据其类型上的这些标志而非名称猜测而摘要视图的生成则依赖Important递归标志。值存储SDObjectData 与 SDObjectPODData对象的值存放在SDObjectData中。对于基础类型它包含一个SDObjectPODDataC 中的 union其中的u、i、d、b、c、id分别以uint64_t、int64_t、double、bool、单字节char、ResourceId形式解释同一个存储同时SDObjectData.str保存字符串内容children保存子节点列表。关键原则存储尺寸与元素大小无关始终以最大精度保存。例如一个 8 位整数在底层仍以完整的 64 位槽位存储只是其SDType.byteSize标注为 1。Python 中的注意事项Python 的整数不区分有符号/无符号因此在读取尤其是修改结构化对象的值时必须通过正确的成员访问。具体而言Python 绑定中SDObject提供了成对的取值/写值成员例如无符号路径obj.uint64以及obj.as_uint64之类的读取辅助用于UnsignedInteger等有符号路径obj.int64等浮点obj.float64/obj.double布尔obj.bool字符obj.character资源obj.resourceId。从源码结构structured_data.h看C 侧提供了丰富的类型化访问器AsUInt64/AsInt64/AsUInt32/AsInt32/AsUInt16/AsInt16/AsUInt8/AsInt8、AsDouble/AsFloat/AsChar/AsString、AsBool、AsResourceId、AsEnumT()等Python 接口文件 renderdoc.i 对其做了相应暴露与重命名。当对象是无符号整数而你通过有符号成员写入一个看起来相同的值时高位解释可能不符合预期——务必与basetype匹配。Buffer 的特殊处理Buffer类型的值不直接内联存储而是保存为一个索引指向SDFile.buffers这个独立缓冲列表中的某一项见下文序列化捕获数据。因此要读取 buffer 内容需要拿到对应SDFile的buffers列表。SDObject 的实用方法SDObject提供了一系列辅助方法用于取值和修改若为可变对象Python 中最常用的包括NumChildren()返回子节点数量GetChild(index)按下标取子节点越界返回NoneFindChild(name)/FindChildRecursively(name)按名称查找子节点后者递归但搜索顺序不保证名称不唯一时需谨慎FindChildByKeyPath(keyPath)按点分隔的键路径查找子节点路径不存在时返回NoneCreateChildByKeyPath(keyPath)按键路径创建子节点按需补建中间节点已存在则直接返回EraseChildByKeyPath(keyPath)按键路径删除子节点连同其后代一起删除不存在则无操作AddChild(child)添加子节点Python 中即DuplicateAndAddChild的重命名会自动深拷贝传入对象见 renderdoc.i 中的%rename(AddChild) SDObject::DuplicateAndAddChildDuplicate()深拷贝整棵子树HasEqualValue(other)递归比较两个对象的值是否相等SetCustomString(str)/SetTypeName(name)为对象附加自定义字符串或自定义类型名前者会同时设置HasCustomString标志。键路径语法foo.bar表示父节点foo中的成员bar数组用数字下标表示如foo.0.bar、foo.1.bar空段被忽略foo..bar与foo.bar等价路径不得为空、不得以点开头若路径中某元素在子节点中不唯一行为未定义因此建议要么全程只用键路径操作要么完全不用。序列化捕获数据SDFile 与 chunks当捕获被加载时其序列化数据全部以结构化数据表示存储根对象为SDFile。SDFile的成员包括chunks按顺序排列的SDChunk列表每个 chunk 对应一次自包含的序列化函数调用buffers被 chunk 引用的缓冲字节列表List[bytes]version结构化流的版本通常仅供内部使用Swap(other)与另一个SDFile交换内容Detach()解除对创建方的依赖。普通打开与 Buffer 的取舍正常打开捕获时缓冲区的内容不会被载入——否则会浪费大量极少被访问的内存。此时结构化数据仍然包含除大 buffer 值之外的全部内容。包含 Buffer 的完整数据要获得包含 buffer 内容的结构化数据必须借助 capture_access 中描述的CaptureFile接口来序列化并加载捕获。这个操作无需回放replay即使捕获已在 UI 中打开也可以执行请求到的SDFile会同时包含buffers因此也兼容任何声明requiresBuffers的导出格式用于CaptureFile.Convert。import renderdoc as rd # 打开本地 .rdc 文件 cap rd.OpenCaptureFile() status cap.OpenFile(example.rdc, , None) if status rd.ResultCode.Succeeded: # 获得包含 buffers 的结构化数据无需回放 sdfile cap.GetStructuredData() print(chunks:, len(sdfile.chunks)) print(buffers:, len(sdfile.buffers)) cap.Shutdown()⚠️重要警告序列化捕获的结构化数据格式完全未文档化且可能随版本变化虽然这些数据通常与 API 函数调用的预期结构高度吻合但并非总是如此——你不应将这份数据的结构当作稳定保证来依赖。其向后兼容性由 RenderDoc 内部序列化机制处理仍可能改变。API 事件与 chunk 的对应关系SDFile.chunks中每个 chunk 对应一次自包含的序列化函数调用。绝大部分 chunk 直接来自应用发出的 API 调用但正如上文警告所说也有部分是 RenderDoc 内部生成的调用。通过APIEvent.chunkIndex可以将给定 API 事件映射到对应的 chunk定义见 data_types.h若chunkIndex不等于APIEvent.NoChunk即~0U则它给出事件在SDFile.chunks列表中的下标NoChunk只会在加载后添加的假标记fake markers事件上出现这类事件没有对应的序列化 chunk。import renderdoc as rd controller ... # 通过 CaptureFile.OpenCapture 获得的 ReplayController sdfile cap.GetStructuredData() events controller.GetRootActions() # 或遍历整个事件树 # 遍历全部 API 事件将事件与 chunk 一一对应 for eid in range(1, controller.GetFirstDrawcall().eventId): # 示意 pass # 对任意 APIEvent可用 chunkIndex 反查结构化数据 def event_chunk(sdfile, event): if event.chunkIndex ! rd.APIEvent.NoChunk: return sdfile.chunks[event.chunkIndex] return None事实上ReplayController的某些查询见 data_types.h 中事件相关工具正是利用chunks[chunkIndex]-name来为事件生成描述字符串。chunk 的结构与元数据每个 chunk 可以视为一个无名字的结构体其子节点通常对应函数的输入参数——但同样不保证有些子节点可能是返回值或内部数据。因此判断一个对象是否应该显示或隐藏应依赖类型上的标志SDTypeFlags例如用Hidden判断是否为实现细节用Important以及递归的ImportantChildren来判断哪些参数在事件的摘要视图中最可能与用户相关、哪些应降低显示优先级。SDChunk继承自SDObject其basetype为Chunk并额外带有metadataSDChunkMetaData记录 chunk 的录制信息字段含义chunkID内部 chunk ID——在特定驱动下唯一flagsSDChunkFlagsNoFlags、OpaqueChunk未支持解码/被跳过的 chunk按不透明字节流保留仍为原生 RDC 格式、HasCallstack是否带调用栈lengthchunk 的字节长度可能比实际数据总和大因为创建时可能用了保守估算以避免回写修正长度threadID录制该 chunk 的线程 IDdurationMicro该 chunk 实际执行耗时微秒-1 表示无效/不存在因为 0 对极快调用也是合法值timestampMicro录制时刻程序启动以来的微秒数callstackCPU 侧调用栈帧列表List[int]实战利用结构化数据遍历事件参数结合以上概念一个典型的 Python 脚本可以这样工作import renderdoc as rd cap rd.OpenCaptureFile() cap.OpenFile(frame.rdc, , None) sdfile cap.GetStructuredData() # 含 buffers 的完整结构化数据 controller cap.OpenCapture(None, None) # 取某事件的 chunk 并检查其参数 def dump_event_params(event): if event.chunkIndex rd.APIEvent.NoChunk: print(event %d has no chunk % event.eventId) return chunk sdfile.chunks[event.chunkIndex] print(event %d - chunk %s (%d children) % (event.eventId, chunk.name, chunk.NumChildren())) for child in chunk: # 用类型标志判断可见性/重要性而不是用名称猜测 if child.type.flags rd.SDTypeFlags.Hidden: continue # 实现细节跳过 important bool(child.type.flags rd.SDTypeFlags.Important) print( %s%s: %s % (* if important else , child.name, child.type.basetype)) # 事件可通过 controller 的 API 获取例如 for e in controller.GetEvents() if hasattr(controller, GetEvents) else []: dump_event_params(e)要点用chunkIndex关联事件与 chunk用NoChunk判断是否存在用SDTypeFlags.Hidden过滤内部字段、用Important生成摘要而非依赖参数名当需要读取 buffer 内容时用SDFile.buffers[索引]间接访问修改值时严格匹配basetype有符号/无符号/浮点/枚举。延伸应用注释Annotations系统结构化数据最直观的应用之一是注释系统详细说明见 Annotation Viewer。应用通过SetCommandAnnotation与SetObjectAnnotation写入注释这些注释最终以SDObject形式呈现命令注释挂在每个事件的APIEvent.annotationsOptional[SDObject]上逐事件存储每个事件可有各自唯一的注释集合对象注释挂在资源的ResourceDescription.annotationsOptional[SDObject]上在捕获结束时保存最新内容不随事件变化。注释以点分隔路径组织成任意层级例如custom.list.0、custom.list.1可构成数组UI 中可右键注释将其作为事件浏览器的一列显示。由于注释本身是SDObject上文所有遍历、键路径查找、标志判断的方法均可直接复用——例如用FindChildByKeyPath(custom.list.0)精确取出某个注释值。总结与最佳实践结构化数据是一棵SDObject树叶节点存值、结构体/数组存子节点类型由SDType.basetypeSDBasicSDTypeFlags完整描述值以最大精度存储在 Python 中读写时务必匹配有符号/无符号/浮点等成员Buffer 值则通过SDFile.buffers索引间接访问SDFile.chunks与APIEvent.chunkIndex对应NoChunk表示无对应 chunkchunk 子节点通常对应输入参数但应依赖Hidden/Important标志判断展示与摘要逻辑而非假定结构序列化数据格式不作保证它是内部格式可能随版本变化脚本不应过度依赖其细节需要 buffer 内容时通过 capture_access 的CaptureFile.GetStructuredData()获取含 buffers 的SDFile无需回放即可完成同一套机制支撑配置与注释GetConfigSetting、APIEvent.annotations、ResourceDescription.annotations均基于结构化对象掌握了本文的方法即可通用于这些场景。进一步阅读capture_access捕获文件访问、Annotation Viewer注释查看器、核心类型定义 structured_data.h、事件定义 data_types.h。赞分享开发工具调试器图形学GPU【免费下载链接】renderdocRenderDoc is a stand-alone graphics debugging tool.项目地址https://gitcode.com/gh_mirrors/re/renderdoc点击查看免费下载相关推荐RenderDoc 结构化数据Structured Data体系详解SDType、SDObject、SDChunk 与 SDFile 的 Python API 全指南RenderDoc 结构化数据Structured Data体系详解SDType、SDObject、SDChunk 与 SDFile 的 Python A开发工具调试器图形学GPURenderDoc 捕获文件导入与导出完全指南结构化数据Structured Data与 XML/XMLZIP 格式实战RenderDoc 捕获文件导入与导出完全指南结构化数据Structured Data与 XML/XMLZIP 格式实战 本篇技术指南围绕 Render开发工具调试器图形学GPUSemantic Kernel 结构化数据连接器Structured Data Connector设计与实战指南Semantic Kernel 结构化数据连接器Structured Data Connector设计与实战指南 本文以 Semantic Kernel 仓人工智能大模型AI AgentAgent 框架多智能体RAG创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
