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

fix: improve doc link navigation and tree display

Browse Source 
- Fix link resolution with proper relative/absolute path handling
- Improve link styling with underline decoration
- Hide leaf nodes from tree, only show directories
- Fix log file path for packaged app
This commit is contained in:
ssdfasd
2026-03-19 12:44:08 +08:00
parent e003fe6513
commit 58a83f445a
1012 changed files with 56880 additions and 22 deletions
Download Patch File Download Diff File Expand all files Collapse all files

26
docs/api/debug/profiler/beginframe.md Normal file
View File

@@ -0,0 +1,26 @@
# Profiler::BeginFrame
```cpp
void BeginFrame()
```
开始一帧的性能分析。记录当前帧的起始时间戳，用于计算帧级别的性能指标。应在每帧渲染开始时调用。
**复杂度：** O(1)
**示例：**
```cpp
#include <XCEngine/Debug/Profiler.h>
void GameLoop() {
XCEngine::Debug::Profiler::Get().BeginFrame();
Update();
Render();
XCEngine::Debug::Profiler::Get().EndFrame();
}
```
## 相关文档
- [Profiler 总览](profiler.md) - 返回类总览

36
docs/api/debug/profiler/beginprofile.md Normal file
View File

@@ -0,0 +1,36 @@
# Profiler::BeginProfile
```cpp
void BeginProfile(const char* name)
```
开始一个性能分析块。将分析节点压入栈中并记录开始时间。每次调用 `BeginProfile` 应与一次 `EndProfile` 配对使用。
**参数：**
- `name` - 分析块的名称，用于在导出结果中标识
**复杂度：** O(1)
**示例：**
```cpp
#include <XCEngine/Debug/Profiler.h>
void ProcessMesh() {
XCEngine::Debug::Profiler::Get().BeginProfile("ProcessMesh");
XCEngine::Debug::Profiler::Get().BeginProfile("ComputeVertices");
ComputeVertices();
XCEngine::Debug::Profiler::Get().EndProfile();
XCEngine::Debug::Profiler::Get().BeginProfile("ComputeIndices");
ComputeIndices();
XCEngine::Debug::Profiler::Get().EndProfile();
XCEngine::Debug::Profiler::Get().EndProfile();
}
```
## 相关文档
- [Profiler 总览](profiler.md) - 返回类总览

26
docs/api/debug/profiler/endframe.md Normal file
View File

@@ -0,0 +1,26 @@
# Profiler::EndFrame
```cpp
void EndFrame()
```
结束一帧的性能分析。记录当前帧的结束时间，计算帧耗时并可用于帧率统计。应在每帧渲染结束时调用。
**复杂度：** O(1)
**示例：**
```cpp
#include <XCEngine/Debug/Profiler.h>
void GameLoop() {
XCEngine::Debug::Profiler::Get().BeginFrame();
Update();
Render();
XCEngine::Debug::Profiler::Get().EndFrame();
}
```
## 相关文档
- [Profiler 总览](profiler.md) - 返回类总览

25
docs/api/debug/profiler/endprofile.md Normal file
View File

@@ -0,0 +1,25 @@
# Profiler::EndProfile
```cpp
void EndProfile()
```
结束当前性能分析块。从栈顶弹出分析节点并计算持续时间（endTime - startTime），将结果保存到样本列表中。
**复杂度：** O(1)
**示例：**
```cpp
#include <XCEngine/Debug/Profiler.h>
void RenderPipeline() {
XCEngine::Debug::Profiler::Get().BeginProfile("RenderPipeline");
// ... 渲染逻辑 ...
XCEngine::Debug::Profiler::Get().EndProfile();
}
```
## 相关文档
- [Profiler 总览](profiler.md) - 返回类总览

45
docs/api/debug/profiler/exportchrometracing.md Normal file
View File

@@ -0,0 +1,45 @@
# Profiler::ExportChromeTracing
```cpp
void ExportChromeTracing(const Containers::String& filePath)
```
**状态：** 此方法目前为空实现，暂未功能。
将收集的性能数据导出为 Chrome Tracing JSON 格式。导出的文件可通过 Chrome 浏览器打开（地址栏输入 `chrome://tracing` 并加载文件）进行可视化分析。
**参数：**
- `filePath` - 输出文件路径
**复杂度：** O(n)，n 为记录的样本数量
**示例：**
```cpp
#include <XCEngine/Debug/Profiler.h>
XCEngine::Debug::Profiler::Get().Initialize();
void RenderFrame() {
XCEngine::Debug::Profiler::Get().BeginFrame();
XE_PROFILE_FUNCTION();
XE_PROFILE_BEGIN("UpdateScene");
UpdateScene();
XE_PROFILE_END();
XE_PROFILE_BEGIN("DrawScene");
DrawScene();
XE_PROFILE_END();
XCEngine::Debug::Profiler::Get().EndFrame();
}
// 运行一段时间后导出
XCEngine::Debug::Profiler::Get().ExportChromeTracing("trace.json");
XCEngine::Debug::Profiler::Get().Shutdown();
```
## 相关文档
- [Profiler 总览](profiler.md) - 返回类总览

22
docs/api/debug/profiler/get.md Normal file
View File

@@ -0,0 +1,22 @@
# Profiler::Get
```cpp
static Profiler& Get()
```
获取 `Profiler` 单例实例。Profiler 使用局部静态变量实现 Meyers' Singleton，确保线程安全且只初始化一次。
**返回：** `Profiler&` - 全局性能分析器实例的引用
**复杂度：** O(1)
**示例：**
```cpp
XCEngine::Debug::Profiler& profiler = XCEngine::Debug::Profiler::Get();
profiler.Initialize();
```
## 相关文档
- [Profiler 总览](profiler.md) - 返回类总览

30
docs/api/debug/profiler/initialize.md Normal file
View File

@@ -0,0 +1,30 @@
# Profiler::Initialize
```cpp
void Initialize()
```
初始化性能分析器。在首次使用性能分析功能前必须调用。初始化内部状态标志，确保分析器已准备好工作。
**注意：** 帧计时器等数据结构在首次 BeginFrame 时自动初始化。
**复杂度：** O(1)
**示例：**
```cpp
#include <XCEngine/Debug/Profiler.h>
int main() {
XCEngine::Debug::Profiler::Get().Initialize();
XCEngine::Debug::Profiler::Get().BeginFrame();
// ... 性能测量 ...
XCEngine::Debug::Profiler::Get().EndFrame();
XCEngine::Debug::Profiler::Get().Shutdown();
return 0;
}
```
## 相关文档
- [Profiler 总览](profiler.md) - 返回类总览

36
docs/api/debug/profiler/markevent.md Normal file
View File

@@ -0,0 +1,36 @@
# Profiler::MarkEvent
```cpp
void MarkEvent(const char* name, uint64_t timestamp, uint32_t threadId)
```
**状态：** 此方法目前为空实现，暂未功能。
在指定时间点标记一个事件。用于记录离散的瞬时事件，如 GPU 命令提交、状态切换等，通常用于多线程性能分析。
**参数：**
- `name` - 事件名称
- `timestamp` - 事件发生的时间戳（微秒）
- `threadId` - 事件所属的线程 ID
**复杂度：** O(1)
**示例：**
```cpp
#include <XCEngine/Debug/Profiler.h>
// 在多线程场景中标记事件
void WorkerThread() {
uint32_t tid = GetCurrentThreadId();
uint64_t ts = GetTickCount();
XCEngine::Debug::Profiler::Get().MarkEvent("TaskStarted", ts, tid);
DoWork();
XCEngine::Debug::Profiler::Get().MarkEvent("TaskCompleted", GetTickCount(), tid);
}
```
## 相关文档
- [Profiler 总览](profiler.md) - 返回类总览

136
docs/api/debug/profiler/profiler.md Normal file
View File

@@ -0,0 +1,136 @@
# 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) - 日志记录器

33
docs/api/debug/profiler/setmarker.md Normal file
View File

@@ -0,0 +1,33 @@
# Profiler::SetMarker
```cpp
void SetMarker(const char* name, uint32_t color)
```
**状态：** 此方法目前为空实现，暂未功能。
在 Chrome Tracing 时间线上设置一个标记点，用于标记特定位置或状态。标记会显示为一条垂直线，便于在性能图中定位关键事件。
**参数：**
- `name` - 标记名称
- `color` - 标记颜色（ABGR 格式）
**复杂度：** O(1)
**示例：**
```cpp
#include <XCEngine/Debug/Profiler.h>
void OnVBlank() {
XCEngine::Debug::Profiler::Get().SetMarker("VBlank", 0xFF00FF00); // 绿色
}
void OnRenderComplete() {
XCEngine::Debug::Profiler::Get().SetMarker("FrameRendered", 0xFFFF0000); // 红色
}
```
## 相关文档
- [Profiler 总览](profiler.md) - 返回类总览

22
docs/api/debug/profiler/shutdown.md Normal file
View File

@@ -0,0 +1,22 @@
# Profiler::Shutdown
```cpp
void Shutdown()
```
关闭性能分析器。清理内部数据结构，停止所有活动分析块，重置状态。在程序退出前调用。
**复杂度：** O(1)
**示例：**
```cpp
XCEngine::Debug::Profiler::Get().Initialize();
// ... 使用 Profiler ...
XCEngine::Debug::Profiler::Get().ExportChromeTracing("profile.json");
XCEngine::Debug::Profiler::Get().Shutdown();
```
## 相关文档
- [Profiler 总览](profiler.md) - 返回类总览