XCEngine/docs/api/debug/profiler/profiler.md

# 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) - 日志记录器