137 lines
3.5 KiB
Markdown
137 lines
3.5 KiB
Markdown
# Profiler
|
||
|
||
**命名空间**: `XCEngine::Debug`
|
||
|
||
**类型**: `class` (singleton)
|
||
|
||
**描述**: 性能分析器单例，用于测量代码块执行时间并支持 Chrome Tracing 格式导出。
|
||
|
||
## 概述
|
||
|
||
`Profiler` 是 XCEngine 的性能分析工具。它通过栈式记录和采样方式跟踪函数执行时间，支持导出为 Chrome Tracing 格式（可通过 Chrome 的 `chrome://tracing` 查看）。
|
||
|
||
## 单例访问
|
||
|
||
| 方法 | 描述 |
|
||
|------|------|
|
||
| `static Profiler& Get()` | 获取单例实例 |
|
||
|
||
## 公共方法
|
||
|
||
| 方法 | 描述 |
|
||
|------|------|
|
||
| `void Initialize()` | [初始化性能分析器](initialize.md) |
|
||
| `void Shutdown()` | [关闭性能分析器](shutdown.md) |
|
||
| `void BeginProfile(const char* name)` | [开始一个性能分析块](beginprofile.md) |
|
||
| `void EndProfile()` | [结束当前性能分析块](endprofile.md) |
|
||
| `void BeginFrame()` | [开始一帧的分析](beginframe.md) |
|
||
| `void EndFrame()` | [结束一帧的分析](endframe.md) |
|
||
| `void MarkEvent(const char* name, uint64_t timestamp, uint32_t threadId)` | [标记一个事件点](markevent.md) |
|
||
| `void SetMarker(const char* name, uint32_t color)` | [设置帧标记](setmarker.md) |
|
||
| `void ExportChromeTracing(const Containers::String& filePath)` | [导出为 Chrome Tracing JSON 格式](exportchrometracing.md) |
|
||
|
||
## 宏定义
|
||
|
||
### XE_PROFILE_BEGIN
|
||
|
||
```cpp
|
||
#define XE_PROFILE_BEGIN(name) XCEngine::Debug::Profiler::Get().BeginProfile(name)
|
||
```
|
||
|
||
开始分析指定名称的代码块。
|
||
|
||
### XE_PROFILE_END
|
||
|
||
```cpp
|
||
#define XE_PROFILE_END() XCEngine::Debug::Profiler::Get().EndProfile()
|
||
```
|
||
|
||
结束当前分析块。
|
||
|
||
### XE_PROFILE_FUNCTION
|
||
|
||
```cpp
|
||
#define XE_PROFILE_FUNCTION() XE_PROFILE_BEGIN(__FUNCTION__)
|
||
```
|
||
|
||
自动使用当前函数名进行分析。
|
||
|
||
## 私有成员
|
||
|
||
### ProfileNode
|
||
|
||
```cpp
|
||
struct ProfileNode {
|
||
const char* name;
|
||
uint64_t startTime;
|
||
uint64_t endTime;
|
||
uint32_t threadId;
|
||
};
|
||
```
|
||
|
||
内部使用的性能分析节点结构，用于在栈上跟踪嵌套的分析块。
|
||
|
||
### ProfileSample
|
||
|
||
```cpp
|
||
struct ProfileSample {
|
||
const char* name;
|
||
uint64_t duration;
|
||
uint32_t threadId;
|
||
};
|
||
```
|
||
|
||
记录单个性能样本的结构，包含名称、持续时间和线程 ID。
|
||
|
||
## 成员变量
|
||
|
||
| 成员 | 类型 | 描述 |
|
||
|------|------|------|
|
||
| `m_profileStack` | `std::vector<ProfileNode>` | 分析块栈，用于跟踪嵌套调用 |
|
||
| `m_samples` | `std::vector<ProfileSample>` | 样本列表，记录完成的性能数据 |
|
||
| `m_frameStartTime` | `uint64_t` | 当前帧开始时间戳（微秒） |
|
||
| `m_initialized` | `bool` | 初始化标志 |
|
||
|
||
## 实现状态
|
||
|
||
以下方法目前为存根（stub）实现，尚未完成功能：
|
||
|
||
| 方法 | 状态 |
|
||
|------|------|
|
||
| `void MarkEvent(const char* name, uint64_t timestamp, uint32_t threadId)` | 存根 |
|
||
| `void SetMarker(const char* name, uint32_t color)` | 存根 |
|
||
| `void ExportChromeTracing(const Containers::String& filePath)` | 存根 |
|
||
|
||
## 使用示例
|
||
|
||
```cpp
|
||
Profiler::Get().Initialize();
|
||
|
||
void RenderFrame() {
|
||
XE_PROFILE_FUNCTION();
|
||
|
||
{
|
||
XE_PROFILE_BEGIN("UpdateGeometry");
|
||
UpdateGeometry();
|
||
XE_PROFILE_END();
|
||
}
|
||
|
||
{
|
||
XE_PROFILE_BEGIN("DrawCalls");
|
||
DrawCalls();
|
||
XE_PROFILE_END();
|
||
}
|
||
}
|
||
|
||
Profiler::Get().BeginFrame();
|
||
// ... 渲染帧 ...
|
||
Profiler::Get().EndFrame();
|
||
Profiler::Get().ExportChromeTracing("profile.json");
|
||
Profiler::Get().Shutdown();
|
||
```
|
||
|
||
## 相关文档
|
||
|
||
- [Debug 模块总览](../debug.md) - 返回模块总览
|
||
- [Logger](../logger/logger.md) - 日志记录器
|