61 lines
3.0 KiB
Markdown
61 lines
3.0 KiB
Markdown
# Debug
|
||
|
||
**命名空间**: `XCEngine::Debug`
|
||
|
||
**类型**: `module`
|
||
|
||
**描述**: 提供日志分发、轻量级 CPU 埋点以及 RenderDoc 捕获集成。
|
||
|
||
## 概述
|
||
|
||
`XCEngine::Debug` 是引擎运行时调试能力的入口模块。它把三个需求放在同一层中统一管理：
|
||
|
||
- 运行日志：通过 `Logger` 将消息分发到控制台、文件或自定义 sink。
|
||
- CPU 埋点：通过 `Profiler` 记录函数段或作用域的耗时。
|
||
- GPU 抓帧：通过 `RenderDocCapture` 在图形测试和工具程序中触发 RenderDoc。
|
||
|
||
当前版本的成熟度并不一致：
|
||
|
||
- `Logger` 与日志 sink 已经可以直接用于编辑器、测试和后端调试。
|
||
- `Profiler` 的接口已经成形，但导出、标记和事件功能目前仍是占位实现。
|
||
- `RenderDocCapture` 是 Windows 平台上的轻量封装，依赖可用的 `renderdoc.dll`。
|
||
|
||
## 设计要点
|
||
|
||
- 统一入口比散落的 `printf` 或后端专用日志更利于跨模块排查问题。
|
||
- sink 模式允许同时输出到多个目标，而不会把输出策略写死在业务代码里。
|
||
- `Profiler` 和 `RenderDocCapture` 都采用单例，目的是让工具、测试和引擎运行时共享一套调试入口。
|
||
- 该模块偏开发期工具能力，不追求零侵入；一些 API 会主动写日志、刷新文件或拉起窗口焦点。
|
||
|
||
## 聚合头文件
|
||
|
||
**头文件**: `XCEngine/Debug/Debug.h`
|
||
|
||
`Debug.h` 是这个模块的 umbrella header。它本身不代表新的运行时类型，而是把 `Logger`、`Profiler`、`RenderDocCapture` 等常用 public header 聚合成一个便利入口。
|
||
|
||
对读者来说，最合理的入口仍然是当前这页，而不是再进入一个同名的 `Debug/Debug.md` 类型页。
|
||
|
||
## 头文件
|
||
|
||
- [ConsoleLogSink](ConsoleLogSink/ConsoleLogSink.md) - `ConsoleLogSink.h`，面向 `stdout` 的日志输出 sink。
|
||
- `Debug.h` - 模块聚合头，说明已并入当前页。
|
||
- [FileLogSink](FileLogSink/FileLogSink.md) - `FileLogSink.h`，将日志追加写入文件。
|
||
- [ILogSink](ILogSink/ILogSink.md) - `ILogSink.h`，日志输出目标接口。
|
||
- [LogCategory](LogCategory/LogCategory.md) - `LogCategory.h`，日志功能分类枚举。
|
||
- [LogEntry](LogEntry/LogEntry.md) - `LogEntry.h`，日志记录载体。
|
||
- [Logger](Logger/Logger.md) - `Logger.h`，全局日志分发中心。
|
||
- [LogLevel](LogLevel/LogLevel.md) - `LogLevel.h`，日志严重级别枚举。
|
||
- [Profiler](Profiler/Profiler.md) - `Profiler.h`，轻量级 CPU 埋点入口。
|
||
- [RenderDocCapture](RenderDocCapture/RenderDocCapture.md) - `RenderDocCapture.h`，RenderDoc 封装。
|
||
|
||
## 相关指南
|
||
|
||
- [Logging Architecture](../../_guides/Debug/Logging-Architecture.md) - 日志系统的角色划分、推荐接线方式和与 Unity 的概念对照。
|
||
- [Profiler Workflow](../../_guides/Debug/Profiler-Workflow.md) - 当前埋点能力的适用边界、典型流程与限制。
|
||
- [RenderDoc Capture Workflow](../../_guides/Debug/RenderDoc-Capture-Workflow.md) - 在图形测试中接入 RenderDoc 的推荐步骤。
|
||
|
||
## 相关文档
|
||
|
||
- [上级目录](../XCEngine.md)
|
||
- [API 总索引](../../main.md)
|