xuanchi/XCEngine
1
1
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: rebuild Debug API content

Browse Source
This commit is contained in:
ssdfasd
2026-03-26 17:21:44 +08:00
parent 122495e581
commit 2e2316aa55
69 changed files with 2371 additions and 1092 deletions
Download Patch File Download Diff File Expand all files Collapse all files

35
docs/api/XCEngine/Debug/Profiler/BeginFrame.md
View File

@@ -1,30 +1,37 @@
# Profiler::BeginFrame
公开方法，详见头文件声明。
标记一帧 profiling 周期的开始。
```cpp
void BeginFrame();
```
该方法声明于 `XCEngine/Debug/Profiler.h`，当前页面用于固定 `Profiler` 类目录下的方法级 canonical 路径。
## 行为说明
**参数：** 无。
当前实现只记录当前微秒时间到内部 `m_frameStartTime`，不会创建样本，也不会清空已有数据。
**返回：** `void` - 无返回值。
这说明它目前更像是为后续“按帧汇总”能力预留入口，而不是已经完整实现的帧级 profiler 边界。
**示例：**
## 参数
- 无。
## 返回值
- 无。
## 线程语义
- 无同步保护；建议在主线程或统一的 profiling 线程中调用。
## 示例
```cpp
#include <XCEngine/Debug/Profiler.h>
void Example() {
XCEngine::Debug::Profiler object;
// 根据上下文补齐参数后调用 Profiler::BeginFrame(...)。
(void)object;
}
auto& profiler = XCEngine::Debug::Profiler::Get();
profiler.BeginFrame();
```
## 相关文档
- [返回类总览](Profiler.md)
- [返回模块目录](../Debug.md)
- [返回类型总览](Profiler.md)
- [EndFrame](EndFrame.md)

48
docs/api/XCEngine/Debug/Profiler/BeginProfile.md
View File

@@ -1,31 +1,51 @@
# Profiler::BeginProfile
公开方法，详见头文件声明。
开始一个具名 profile 区段。
```cpp
void BeginProfile(const char* name);
```
该方法声明于 `XCEngine/Debug/Profiler.h`，当前页面用于固定 `Profiler` 类目录下的方法级 canonical 路径。
## 行为说明
**参数：**
- `name` - 参数语义详见头文件声明。
当前实现会把一个新的 `ProfileNode` 压入内部栈，记录：
**返回：** `void` - 无返回值。
- `name`
- 当前微秒时间
- 当前线程哈希值
**示例：**
它不会检查：
- `Profiler` 是否已经 `Initialize`
- `name` 是否为空
- 是否来自同一线程
因此当前 API 更适合“明确受控、单线程成对调用”的埋点场景。
## 参数
- `name` - 区段名称，通常使用固定字符串或函数名。
## 返回值
- 无。
## 线程语义
- 必须与 [EndProfile](EndProfile.md) 在同一线程、按栈顺序配对使用。
## 示例
```cpp
#include <XCEngine/Debug/Profiler.h>
using namespace XCEngine::Debug;
void Example() {
XCEngine::Debug::Profiler object;
// 根据上下文补齐参数后调用 Profiler::BeginProfile(...)。
(void)object;
}
Profiler::Get().BeginProfile("ShadowPass");
// ... CPU work ...
Profiler::Get().EndProfile();
```
## 相关文档
- [返回类总览](Profiler.md)
- [返回模块目录](../Debug.md)
- [返回类型总览](Profiler.md)
- [EndProfile](EndProfile.md)
- [Profiler Workflow](../../../_guides/Debug/Profiler-Workflow.md)

40
docs/api/XCEngine/Debug/Profiler/EndFrame.md
View File

@@ -1,30 +1,42 @@
# Profiler::EndFrame
公开方法，详见头文件声明。
结束当前帧的 profiling 周期。
```cpp
void EndFrame();
```
该方法声明于 `XCEngine/Debug/Profiler.h`，当前页面用于固定 `Profiler` 类目录下的方法级 canonical 路径。
## 行为说明
**参数：** 无。
当前实现会直接清空内部 `m_samples` 数组，而不会导出、返回或持久化这些样本。
**返回：** `void` - 无返回值。
这意味着当前版本里：
**示例：**
- `BeginProfile` / `EndProfile` 采集到的数据是短暂的。
- 如果你在同一帧内没有其它方式读取样本，调用 `EndFrame` 后这些数据就会被丢弃。
## 参数
- 无。
## 返回值
- 无。
## 线程语义
- 无同步保护；建议与 [BeginFrame](BeginFrame.md) 在同一线程调用。
## 示例
```cpp
#include <XCEngine/Debug/Profiler.h>
void Example() {
XCEngine::Debug::Profiler object;
// 根据上下文补齐参数后调用 Profiler::EndFrame(...)。
(void)object;
}
auto& profiler = XCEngine::Debug::Profiler::Get();
profiler.BeginFrame();
// ...
profiler.EndFrame();
```
## 相关文档
- [返回类总览](Profiler.md)
- [返回模块目录](../Debug.md)
- [返回类型总览](Profiler.md)
- [BeginFrame](BeginFrame.md)

44
docs/api/XCEngine/Debug/Profiler/EndProfile.md
View File

@@ -1,30 +1,48 @@
# Profiler::EndProfile
公开方法，详见头文件声明。
结束最近一次开始的 profile 区段，并记录其耗时。
```cpp
void EndProfile();
```
该方法声明于 `XCEngine/Debug/Profiler.h`，当前页面用于固定 `Profiler` 类目录下的方法级 canonical 路径。
## 行为说明
**参数：** 无。
当前实现会：
**返回：** `void` - 无返回值。
1. 检查内部栈是否为空；为空则直接返回。
2. 读取当前微秒时间作为结束时间。
3. 弹出最近一个 `ProfileNode`。
4. 计算区段耗时并把结果追加到内部 `m_samples`。
**示例：**
当前不会：
- 验证开始与结束是否发生在同一线程。
- 提供读取样本的公开 API。
## 参数
- 无。
## 返回值
- 无。
## 线程语义
- 必须与 [BeginProfile](BeginProfile.md) 形成正确的 LIFO 配对。
## 示例
```cpp
#include <XCEngine/Debug/Profiler.h>
using namespace XCEngine::Debug;
void Example() {
XCEngine::Debug::Profiler object;
// 根据上下文补齐参数后调用 Profiler::EndProfile(...)。
(void)object;
}
Profiler::Get().BeginProfile("FrameBuild");
// ...
Profiler::Get().EndProfile();
```
## 相关文档
- [返回类总览](Profiler.md)
- [返回模块目录](../Debug.md)
- [返回类型总览](Profiler.md)
- [BeginProfile](BeginProfile.md)

35
docs/api/XCEngine/Debug/Profiler/ExportChromeTracing.md
View File

@@ -1,31 +1,36 @@
# Profiler::ExportChromeTracing
公开方法，详见头文件声明。
将采样结果导出为 Chrome Tracing 格式文件。
```cpp
void ExportChromeTracing(const Containers::String& filePath);
```
该方法声明于 `XCEngine/Debug/Profiler.h`，当前页面用于固定 `Profiler` 类目录下的方法级 canonical 路径。
## 行为说明
**参数：**
- `filePath` - 参数语义详见头文件声明。
当前实现是空函数，不会创建文件，也不会导出任何样本。
**返回：** `void` - 无返回值。
从 API 形状可以推断，这个接口是为后续接入 Chrome Trace 或 Perfetto 类工具预留的；但在当前版本中，调用它不会产生可见效果。
**示例：**
## 参数
- `filePath` - 预期的输出文件路径。当前实现不会实际使用该参数。
## 返回值
- 无。
## 线程语义
- 当前为空实现，无额外线程语义。
## 示例
```cpp
#include <XCEngine/Debug/Profiler.h>
void Example() {
XCEngine::Debug::Profiler object;
// 根据上下文补齐参数后调用 Profiler::ExportChromeTracing(...)。
(void)object;
}
XCEngine::Debug::Profiler::Get().ExportChromeTracing("trace.json");
```
## 相关文档
- [返回类总览](Profiler.md)
- [返回模块目录](../Debug.md)
- [返回类型总览](Profiler.md)
- [Profiler Workflow](../../../_guides/Debug/Profiler-Workflow.md)

32
docs/api/XCEngine/Debug/Profiler/Get.md
View File

@@ -1,29 +1,35 @@
# Profiler::Get
获取相关状态或对象。
获取进程级全局 `Profiler` 实例。
```cpp
static Profiler& Get();
```
该方法声明于 `XCEngine/Debug/Profiler.h`，当前页面用于固定 `Profiler` 类目录下的方法级 canonical 路径。
## 行为说明
**参数：** 无。
当前实现使用函数内静态对象保存单例，整个进程只存在一个 `Profiler` 实例。它不会在 `Get()` 时自动初始化或清空样本。
**返回：** `Profiler&` - 返回值语义详见头文件声明。
## 参数
**示例：**
- 无。
## 返回值
- `Profiler&` - 全局 profiler 引用。
## 线程语义
- 单例构造本身由 C++ 保证线程安全；后续使用仍需遵守当前 profiler 不支持并发埋点的限制。
## 示例
```cpp
#include <XCEngine/Debug/Profiler.h>
void Example() {
auto& instance = XCEngine::Debug::Profiler::Get();
(void)instance;
}
XCEngine::Debug::Profiler& profiler = XCEngine::Debug::Profiler::Get();
profiler.Initialize();
```
## 相关文档
- [返回类总览](Profiler.md)
- [返回模块目录](../Debug.md)
- [返回类型总览](Profiler.md)
- [Initialize](Initialize.md)

37
docs/api/XCEngine/Debug/Profiler/Initialize.md
View File

@@ -1,30 +1,39 @@
# Profiler::Initialize
初始化内部状态。
把 `Profiler` 标记为已初始化。
```cpp
void Initialize();
```
该方法声明于 `XCEngine/Debug/Profiler.h`，当前页面用于固定 `Profiler` 类目录下的方法级 canonical 路径。
## 行为说明
**参数：** 无。
当前实现是幂等的：
**返回：** `void` - 无返回值。
- 如果已经初始化，直接返回。
- 如果尚未初始化，仅把 `m_initialized` 设为 `true`。
**示例：**
它不会分配新资源，也不会清理旧样本。更准确地说，当前 `Initialize` 只是一个状态标记，而不是完整自举流程。
## 参数
- 无。
## 返回值
- 无。
## 线程语义
- 当前没有同步逻辑；建议在单线程启动阶段调用。
## 示例
```cpp
#include <XCEngine/Debug/Profiler.h>
void Example() {
XCEngine::Debug::Profiler object;
// 根据上下文补齐参数后调用 Profiler::Initialize(...)。
(void)object;
}
XCEngine::Debug::Profiler::Get().Initialize();
```
## 相关文档
- [返回类总览](Profiler.md)
- [返回模块目录](../Debug.md)
- [返回类型总览](Profiler.md)
- [Shutdown](Shutdown.md)

39
docs/api/XCEngine/Debug/Profiler/MarkEvent.md
View File

@@ -1,33 +1,38 @@
# Profiler::MarkEvent
公开方法，详见头文件声明。
记录一个带时间戳的事件标记。
```cpp
void MarkEvent(const char* name, uint64_t timestamp, uint32_t threadId);
```
该方法声明于 `XCEngine/Debug/Profiler.h`，当前页面用于固定 `Profiler` 类目录下的方法级 canonical 路径。
## 行为说明
**参数：**
- `name` - 参数语义详见头文件声明。
- `timestamp` - 参数语义详见头文件声明。
- `threadId` - 参数语义详见头文件声明。
当前实现是空函数，不会保存事件，也不会产生输出。
**返回：** `void` - 无返回值。
从接口形状看，它原本应该用于把离散事件插入时间线上，但这一能力目前尚未接入内部样本系统。
**示例：**
## 参数
- `name` - 事件名称。当前实现不会使用。
- `timestamp` - 事件时间戳。当前实现不会使用。
- `threadId` - 事件线程 ID。当前实现不会使用。
## 返回值
- 无。
## 线程语义
- 当前为空实现，无额外线程语义。
## 示例
```cpp
#include <XCEngine/Debug/Profiler.h>
void Example() {
XCEngine::Debug::Profiler object;
// 根据上下文补齐参数后调用 Profiler::MarkEvent(...)。
(void)object;
}
XCEngine::Debug::Profiler::Get().MarkEvent("GPUSubmit", 0, 0);
```
## 相关文档
- [返回类总览](Profiler.md)
- [返回模块目录](../Debug.md)
- [返回类型总览](Profiler.md)
- [SetMarker](SetMarker.md)

66
docs/api/XCEngine/Debug/Profiler/Profiler.md
View File

@@ -6,34 +6,60 @@
**头文件**: `XCEngine/Debug/Profiler.h`
**描述**: 定义 `XCEngine/Debug` 子目录中的 `Profiler` public API。
**描述**: 提供轻量级 CPU 埋点入口，用于记录成对的 profile 区段。
## 概述
`Profiler.h` 是 `XCEngine/Debug` 子目录 下的 public header，当前页面作为平行目录中的 canonical 总览，用于汇总该头文件暴露的主要声明。
`Profiler` 的 API 形状明显面向“开发期埋点”和“后续时间线导出”场景，但当前实现仍处于非常早期的阶段。它已经能够记录一组成对的 `BeginProfile` / `EndProfile` 调用时长，却还没有提供读取样本、可视化时间线或导出 Chrome Trace 的完整工作流。
## 声明概览
可以把它理解为：
| 声明 | 类型 | 说明 |
|------|------|------|
| `Profiler` | `class` | 头文件中的公开声明。 |
- 设计方向上类似轻量版的引擎内 CPU 埋点器；
- 但当前能力远不等同于 Unity Profiler 这类成熟的分析器。
## 公共方法
## 当前实现能力
| 方法 | 描述 |
- [BeginProfile](BeginProfile.md) / [EndProfile](EndProfile.md) 会把区段时长记录到内部样本数组。
- [BeginFrame](BeginFrame.md) 只记录一帧开始时间。
- [EndFrame](EndFrame.md) 当前会直接清空样本数组。
- [MarkEvent](MarkEvent.md)、[SetMarker](SetMarker.md) 和 [ExportChromeTracing](ExportChromeTracing.md) 目前都是空实现。
## 生命周期
- [Get](Get.md) 返回进程级单例。
- [Initialize](Initialize.md) 只设置初始化标志。
- [Shutdown](Shutdown.md) 清空样本与栈状态。
## 线程语义
- 当前实现没有任何锁，也不是按线程分桶存储。
- `m_profileStack` 是单个全局栈，因此 `BeginProfile` / `EndProfile` 只应在同一线程、同一调用栈上成对使用。
- 如果多个线程并发使用同一个 `Profiler`，样本次序和栈配对都可能被破坏。
## 宏
- `XE_PROFILE_BEGIN(name)` 开始一个具名区段。
- `XE_PROFILE_END()` 结束最近一次开始的区段。
- `XE_PROFILE_FUNCTION()` 使用当前函数名作为区段名。
这些宏是最适合当前实现的接入方式，因为它们几乎不引入额外样板代码。
## 公开方法
| 方法 | 说明 |
|------|------|
| [Get](Get.md) | 获取相关状态或对象。 |
| [Initialize](Initialize.md) | 初始化内部状态。 |
| [Shutdown](Shutdown.md) | 关闭并清理内部状态。 |
| [BeginProfile](BeginProfile.md) | 公开方法，详见头文件声明。 |
| [EndProfile](EndProfile.md) | 公开方法，详见头文件声明。 |
| [BeginFrame](BeginFrame.md) | 公开方法，详见头文件声明。 |
| [EndFrame](EndFrame.md) | 公开方法，详见头文件声明。 |
| [MarkEvent](MarkEvent.md) | 公开方法，详见头文件声明。 |
| [SetMarker](SetMarker.md) | 设置相关状态或配置。 |
| [ExportChromeTracing](ExportChromeTracing.md) | 公开方法，详见头文件声明。 |
| [Get](Get.md) | 获取全局 `Profiler` 实例。 |
| [Initialize](Initialize.md) | 初始化 profiler 状态。 |
| [Shutdown](Shutdown.md) | 清空内部记录。 |
| [BeginProfile](BeginProfile.md) | 开始一个 profile 区段。 |
| [EndProfile](EndProfile.md) | 结束最近一个区段并记录时长。 |
| [BeginFrame](BeginFrame.md) | 标记帧开始。 |
| [EndFrame](EndFrame.md) | 结束当前帧并清空当前样本。 |
| [MarkEvent](MarkEvent.md) | 预留的事件标记接口。 |
| [SetMarker](SetMarker.md) | 预留的 marker 接口。 |
| [ExportChromeTracing](ExportChromeTracing.md) | 预留的导出接口。 |
## 相关文档
- [当前目录](../Debug.md) - 返回 `Debug` 平行目录
- [API 总索引](../../../main.md) - 返回顶层索引
- [当前模块](../Debug.md)
- [Profiler Workflow](../../../_guides/Debug/Profiler-Workflow.md)

37
docs/api/XCEngine/Debug/Profiler/SetMarker.md
View File

@@ -1,32 +1,37 @@
# Profiler::SetMarker
设置相关状态或配置。
设置一个可视化 marker。
```cpp
void SetMarker(const char* name, uint32_t color);
```
该方法声明于 `XCEngine/Debug/Profiler.h`，当前页面用于固定 `Profiler` 类目录下的方法级 canonical 路径。
## 行为说明
**参数：**
- `name` - 参数语义详见头文件声明。
- `color` - 参数语义详见头文件声明。
当前实现是空函数，不会保存 marker，也不会改变任何采样结果。
**返回：** `void` - 无返回值。
从接口设计看，这更像是为后续调试 UI 或时间线着色预留的扩展点，而不是现阶段可依赖的功能。
**示例：**
## 参数
- `name` - marker 名称。当前实现不会使用。
- `color` - marker 颜色。当前实现不会使用。
## 返回值
- 无。
## 线程语义
- 当前为空实现，无额外线程语义。
## 示例
```cpp
#include <XCEngine/Debug/Profiler.h>
void Example() {
XCEngine::Debug::Profiler object;
// 根据上下文补齐参数后调用 Profiler::SetMarker(...)。
(void)object;
}
XCEngine::Debug::Profiler::Get().SetMarker("ShadowPass", 0xff00ff00u);
```
## 相关文档
- [返回类总览](Profiler.md)
- [返回模块目录](../Debug.md)
- [返回类型总览](Profiler.md)
- [MarkEvent](MarkEvent.md)

38
docs/api/XCEngine/Debug/Profiler/Shutdown.md
View File

@@ -1,30 +1,40 @@
# Profiler::Shutdown
关闭并清理内部状态。
清空 profiler 内部状态。
```cpp
void Shutdown();
```
该方法声明于 `XCEngine/Debug/Profiler.h`，当前页面用于固定 `Profiler` 类目录下的方法级 canonical 路径。
## 行为说明
**参数：** 无。
当前实现会：
**返回：** `void` - 无返回值。
- 清空 `m_samples`
- 清空 `m_profileStack`
- 把 `m_initialized` 设为 `false`
**示例：**
它不会导出当前样本，也不会保留历史结果。
## 参数
- 无。
## 返回值
- 无。
## 线程语义
- 应在不再有 profile 区段写入时调用。
## 示例
```cpp
#include <XCEngine/Debug/Profiler.h>
void Example() {
XCEngine::Debug::Profiler object;
// 根据上下文补齐参数后调用 Profiler::Shutdown(...)。
(void)object;
}
XCEngine::Debug::Profiler::Get().Shutdown();
```
## 相关文档
- [返回类总览](Profiler.md)
- [返回模块目录](../Debug.md)
- [返回类型总览](Profiler.md)
- [Initialize](Initialize.md)