# Profiler

**命名空间**: `XCEngine::Debug`

**类型**: `class` (singleton)

**描述**: 性能分析器单例，用于测量代码块执行时间并支持 Chrome Tracing 格式导出。

## 概述

`Profiler` 是 XCEngine 的性能分析工具。它通过栈式记录和采样方式跟踪函数执行时间，支持导出为 Chrome Tracing 格式（可通过 Chrome 的 `chrome://tracing` 查看）。

## 单例访问

| 方法 | 描述 |
|------|------|
| `static Profiler& Get()` | 获取单例实例 |

## 公共方法

### 生命周期

| 方法 | 描述 |
|------|------|
| `void Initialize()` | 初始化性能分析器 |
| `void Shutdown()` | 关闭性能分析器 |

### 性能测量

| 方法 | 描述 |
|------|------|
| `void BeginProfile(const char* name)` | 开始一个性能分析块 |
| `void EndProfile()` | 结束当前性能分析块 |

### 帧管理

| 方法 | 描述 |
|------|------|
| `void BeginFrame()` | 开始一帧的分析 |
| `void EndFrame()` | 结束一帧的分析 |

### 事件标记

| 方法 | 描述 |
|------|------|
| `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)` | 导出为 Chrome Tracing JSON 格式 |

## 宏定义

### 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__)
```

自动使用当前函数名进行分析。

## 使用示例

```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();

// 导出 Chrome Tracing 格式
Profiler::Get().ExportChromeTracing("profile.json");

Profiler::Get().Shutdown();
```

## 相关文档

- [Logger](./debug-logger.md) - 日志记录器