# Profiler::BeginProfile

开始一个具名 profile 区段。

```cpp
void BeginProfile(const char* name);
```

## 行为说明

当前实现会把一个新的 `ProfileNode` 压入内部栈，记录：

- `name`
- 当前微秒时间
- 当前线程哈希值

它不会检查：

- `Profiler` 是否已经 `Initialize`
- `name` 是否为空
- 是否来自同一线程

因此当前 API 更适合“明确受控、单线程成对调用”的埋点场景。

## 参数

- `name` - 区段名称，通常使用固定字符串或函数名。

## 返回值

- 无。

## 线程语义

- 必须与 [EndProfile](EndProfile.md) 在同一线程、按栈顺序配对使用。

## 示例

```cpp
using namespace XCEngine::Debug;

Profiler::Get().BeginProfile("ShadowPass");
// ... CPU work ...
Profiler::Get().EndProfile();
```

## 相关文档

- [返回类型总览](Profiler.md)
- [EndProfile](EndProfile.md)
- [Profiler Workflow](../../../_guides/Debug/Profiler-Workflow.md)