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

docs: 重构 API 文档结构并修正源码准确性

Browse Source 
- 重组文档目录结构: 每个模块的概述页移动到模块子目录
- 重命名 index.md 为 main.md
- 修正所有模块文档中的错误:
  - math: FromEuler→FromEulerAngles, TransformDirection 包含缩放, Box 是 OBB, Color::ToRGBA 格式
  - containers: 新增 operator==/!= 文档, 补充 std::hash DJB 算法细节
  - core: 修复 types 链接错误
  - debug: LogLevelToString 返回大写, timestamp 是秒, Profiler 空实现标注, Windows API vs ANSI
  - memory: 修复头文件路径, malloc vs operator new, 新增方法文档
  - resources: 修复 Shader/Texture 链接错误
  - threading: TaskSystem::Wait 空实现标注, ReadWriteLock 重入描述, LambdaTask 链接
- 验证: fix_links.py 确认 0 个断裂引用
This commit is contained in:
ssdfasd
2026-03-19 00:22:30 +08:00
parent d0e16962c8
commit dc850d7739
1012 changed files with 26673 additions and 9222 deletions
Download Patch File Download Diff File Expand all files Collapse all files

20
docs/api/debug/consolelogsink/consolelogsink.md Normal file
View File

@@ -0,0 +1,20 @@
# ConsoleLogSink::ConsoleLogSink
```cpp
ConsoleLogSink()
```
默认构造函数。创建一个 `ConsoleLogSink` 实例，默认启用彩色输出，最小日志级别为 `Verbose`。
**复杂度：** O(1)
**示例：**
```cpp
auto sink = std::make_unique<XCEngine::Debug::ConsoleLogSink>();
XCEngine::Debug::Logger::Get().AddSink(std::move(sink));
```
## 相关文档
- [ConsoleLogSink 总览](consolelogsink.md) - 返回类总览

22
docs/api/debug/consolelogsink/flush.md Normal file
View File

@@ -0,0 +1,22 @@
# ConsoleLogSink::Flush
```cpp
void Flush() override
```
刷新标准输出流（stdout），调用 `fflush(stdout)` 确保所有待输出的日志内容立即显示在控制台上。
**复杂度：** O(1)
**示例：**
```cpp
auto sink = std::make_unique<XCEngine::Debug::ConsoleLogSink>();
XCEngine::Debug::Logger::Get().AddSink(std::move(sink));
// 在程序异常退出前确保日志已输出
XCEngine::Debug::Logger::Get().Flush();
```
## 相关文档
- [ConsoleLogSink 总览](consolelogsink.md) - 返回类总览

25
docs/api/debug/consolelogsink/log.md Normal file
View File

@@ -0,0 +1,25 @@
# ConsoleLogSink::Log
```cpp
void Log(const LogEntry& entry) override
```
将日志输出到控制台。根据 `LogEntry` 的级别和分类格式化输出内容，并根据 `m_colorOutput` 设置决定是否使用 Windows 控制台颜色 API。如果日志级别低于设置的最小级别，则不输出。
**参数：**
- `entry` - 日志条目
**复杂度：** O(1)
**示例：**
```cpp
auto sink = std::make_unique<XCEngine::Debug::ConsoleLogSink>();
// Log 方法由 Logger 在内部调用，用户无需直接调用
XCEngine::Debug::Logger::Get().AddSink(std::move(sink));
XCEngine::Debug::Logger::Get().Info(XCEngine::Debug::LogCategory::General, "Hello console");
```
## 相关文档
- [ConsoleLogSink 总览](consolelogsink.md) - 返回类总览

24
docs/api/debug/consolelogsink/setcoloroutput.md Normal file
View File

@@ -0,0 +1,24 @@
# ConsoleLogSink::SetColorOutput
```cpp
void SetColorOutput(bool enable)
```
启用或禁用控制台彩色输出。启用后，不同日志级别使用 Windows 控制台颜色 API 输出，便于快速区分日志类型。
**参数：**
- `enable` - true 启用彩色输出，false 禁用
**复杂度：** O(1)
**示例：**
```cpp
auto sink = std::make_unique<XCEngine::Debug::ConsoleLogSink>();
sink->SetColorOutput(false); // 禁用颜色（适合日志文件或 CI 环境）
XCEngine::Debug::Logger::Get().AddSink(std::move(sink));
```
## 相关文档
- [ConsoleLogSink 总览](consolelogsink.md) - 返回类总览

24
docs/api/debug/consolelogsink/setminimumlevel.md Normal file
View File

@@ -0,0 +1,24 @@
# ConsoleLogSink::SetMinimumLevel
```cpp
void SetMinimumLevel(LogLevel level)
```
设置该 Sink 的最小输出级别。此设置仅影响当前 Sink，不会影响 Logger 的全局级别过滤。
**参数：**
- `level` - 最小日志级别
**复杂度：** O(1)
**示例：**
```cpp
auto sink = std::make_unique<XCEngine::Debug::ConsoleLogSink>();
sink->SetMinimumLevel(XCEngine::Debug::LogLevel::Warning); // 控制台只显示警告及以上
XCEngine::Debug::Logger::Get().AddSink(std::move(sink));
```
## 相关文档
- [ConsoleLogSink 总览](consolelogsink.md) - 返回类总览

13
docs/api/debug/consolelogsink/~consolelogsink.md Normal file
View File

@@ -0,0 +1,13 @@
# ConsoleLogSink::~ConsoleLogSink
```cpp
~ConsoleLogSink() override
```
析构函数。销毁 `ConsoleLogSink` 实例，释放相关资源。
**复杂度：** O(1)
## 相关文档
- [ConsoleLogSink 总览](consolelogsink.md) - 返回类总览

52
docs/api/debug/debug-consolelogsink.md
View File

@@ -1,52 +0,0 @@
# ConsoleLogSink
**命名空间**: `XCEngine::Debug`
**类型**: `class`
**描述**: 控制台日志输出槽，将日志输出到标准控制台，支持彩色输出。
## 概述
`ConsoleLogSink` 是 `ILogSink` 的控制台实现。它将日志输出到 stdout/stderr，支持按日志级别设置不同颜色。
## 公共方法
### 构造/析构
| 方法 | 描述 |
|------|------|
| `ConsoleLogSink()` | 默认构造函数 |
| `~ConsoleLogSink()` | 析构函数 |
### ILogSink 实现
| 方法 | 描述 |
|------|------|
| `void Log(const LogEntry& entry) override` | 输出日志到控制台 |
| `void Flush() override` | 刷新标准输出流 |
### 配置
| 方法 | 描述 |
|------|------|
| `void SetColorOutput(bool enable)` | 启用/禁用彩色输出 |
| `void SetMinimumLevel(LogLevel level)` | 设置最小输出级别 |
## 使用示例
```cpp
// 创建并配置
auto sink = std::make_unique<ConsoleLogSink>();
sink->SetColorOutput(true);
sink->SetMinimumLevel(LogLevel::Debug);
// 添加到 Logger
Logger::Get().AddSink(std::move(sink));
```
## 相关文档
- [Logger](./debug-logger.md) - 日志记录器
- [ILogSink](./debug-ilogsink.md) - 日志输出接口
- [FileLogSink](./debug-filelogsink.md) - 文件输出

47
docs/api/debug/debug-filelogsink.md
View File

@@ -1,47 +0,0 @@
# FileLogSink
**命名空间**: `XCEngine::Debug`
**类型**: `class`
**描述**: 文件日志输出槽，将日志持久化到磁盘文件。
## 概述
`FileLogSink` 是 `ILogSink` 的文件实现。它使用 `FileWriter` 将日志追加写入文件，支持自动换行和缓冲区刷新。
## 公共方法
### 构造/析构
| 方法 | 描述 |
|------|------|
| `FileLogSink(const Containers::String& filePath)` | 构造函数，指定文件路径 |
| `~FileLogSink()` | 析构函数 |
### ILogSink 实现
| 方法 | 描述 |
|------|------|
| `void Log(const LogEntry& entry) override` | 将日志追加写入文件 |
| `void Flush() override` | 刷新文件缓冲区 |
## 使用示例
```cpp
// 创建文件日志输出
auto fileSink = std::make_unique<FileLogSink>("logs/app.log");
// 添加到 Logger
Logger::Get().AddSink(std::move(fileSink));
// 日志将自动写入文件
XE_LOG(LogCategory::General, LogLevel::Info, "Game started");
```
## 相关文档
- [Logger](./debug-logger.md) - 日志记录器
- [ILogSink](./debug-ilogsink.md) - 日志输出接口
- [ConsoleLogSink](./debug-consolelogsink.md) - 控制台输出
- [Core/FileWriter](../core/core-filewriter.md) - 文件写入工具

18
docs/api/debug/debug-overview.md → docs/api/debug/debug.md
View File

@@ -16,19 +16,19 @@ Debug 模块提供了一套完整的调试工具，包括日志系统和性能
| 组件 | 文件 | 描述 |
|------|------|------|
| [Logger](./debug-logger.md) | `Logger.h` | 日志记录器 |
| [ILogSink](./debug-ilogsink.md) | `ILogSink.h` | 日志输出接口 |
| [ConsoleLogSink](./debug-consolelogsink.md) | `ConsoleLogSink.h` | 控制台输出 |
| [FileLogSink](./debug-filelogsink.md) | `FileLogSink.h` | 文件输出 |
| [LogLevel](./debug-loglevel.md) | `LogLevel.h` | 日志级别枚举 |
| [LogCategory](./debug-logcategory.md) | `LogCategory.h` | 日志分类枚举 |
| [LogEntry](./debug-logentry.md) | `LogEntry.h` | 日志条目结构 |
| [Logger](logger/logger.md) | `Logger.h` | 日志记录器 |
| [ILogSink](ilogsink/ilogsink.md) | `ILogSink.h` | 日志输出接口 |
| [ConsoleLogSink](consolelogsink/consolelogsink.md) | `ConsoleLogSink.h` | 控制台输出 |
| [FileLogSink](filelogsink/filelogsink.md) | `FileLogSink.h` | 文件输出 |
| [LogLevel](loglevel/loglevel.md) | `LogLevel.h` | 日志级别枚举 |
| [LogCategory](logcategory/logcategory.md) | `LogCategory.h` | 日志分类枚举 |
| [LogEntry](logentry/logentry.md) | `LogEntry.h` | 日志条目结构 |
### 性能分析
| 组件 | 文件 | 描述 |
|------|------|------|
| [Profiler](./debug-profiler.md) | `Profiler.h` | 性能分析器 |
| [Profiler](profiler/profiler.md) | `Profiler.h` | 性能分析器 |
## 日志级别
@@ -80,4 +80,4 @@ if (condition) {
## 相关文档
- [Profiler](./debug-profiler.md) - 性能分析器
- [Profiler](profiler/profiler.md) - 性能分析器

23
docs/api/debug/filelogsink/filelogsink.md Normal file
View File

@@ -0,0 +1,23 @@
# FileLogSink::FileLogSink
```cpp
FileLogSink(const Containers::String& filePath)
```
构造函数，打开指定路径的文件用于日志写入。如果文件已存在，则追加写入；如果不存在，则创建新文件。
**参数：**
- `filePath` - 日志文件路径
**复杂度：** O(1)
**示例：**
```cpp
auto fileSink = std::make_unique<XCEngine::Debug::FileLogSink>("logs/engine.log");
XCEngine::Debug::Logger::Get().AddSink(std::move(fileSink));
```
## 相关文档
- [FileLogSink 总览](filelogsink.md) - 返回类总览

24
docs/api/debug/filelogsink/flush.md Normal file
View File

@@ -0,0 +1,24 @@
# FileLogSink::Flush
```cpp
void Flush() override
```
刷新文件缓冲区，调用底层 `FileWriter` 的 flush 方法确保所有待写入的日志数据已实际写入磁盘。
**复杂度：** O(1)
**示例：**
```cpp
auto fileSink = std::make_unique<XCEngine::Debug::FileLogSink>("logs/app.log");
XCEngine::Debug::Logger::Get().AddSink(std::move(fileSink));
// 关键操作后立即刷新
XCEngine::Debug::Logger::Get().Info(XCEngine::Debug::LogCategory::General, "Checkpoint saved");
// 确保写入磁盘
XCEngine::Debug::Logger::Get().Flush();
```
## 相关文档
- [FileLogSink 总览](filelogsink.md) - 返回类总览

25
docs/api/debug/filelogsink/log.md Normal file
View File

@@ -0,0 +1,25 @@
# FileLogSink::Log
```cpp
void Log(const LogEntry& entry) override
```
将日志条目追加写入文件。根据 `LogEntry` 的各字段格式化日志行，包括时间戳、级别、分类、消息，并追加到文件末尾。
**参数：**
- `entry` - 日志条目
**复杂度：** O(m)，m 为消息长度
**示例：**
```cpp
auto fileSink = std::make_unique<XCEngine::Debug::FileLogSink>("logs/app.log");
XCEngine::Debug::Logger::Get().AddSink(std::move(fileSink));
// Log 方法由 Logger 在内部调用
XCEngine::Debug::Logger::Get().Error(XCEngine::Debug::LogCategory::FileSystem, "File not found");
```
## 相关文档
- [FileLogSink 总览](filelogsink.md) - 返回类总览

13
docs/api/debug/filelogsink/~filelogsink.md Normal file
View File

@@ -0,0 +1,13 @@
# FileLogSink::~FileLogSink
```cpp
~FileLogSink() override
```
析构函数。销毁 `FileLogSink` 实例，调用 `Flush()` 确保所有日志数据写入文件，然后关闭文件句柄。
**复杂度：** O(1)
## 相关文档
- [FileLogSink 总览](filelogsink.md) - 返回类总览

32
docs/api/debug/ilogsink/flush.md Normal file
View File

@@ -0,0 +1,32 @@
# ILogSink::Flush
```cpp
virtual void Flush() = 0
```
刷新输出缓冲区，确保所有待写入的日志数据已实际写入目标介质。对于文件类 Sink，应调用底层文件系统的 flush；对于网络类 Sink，应发送缓冲区中的数据。
**复杂度：** O(1)
**示例：**
```cpp
class BufferedLogSink : public XCEngine::Debug::ILogSink {
private:
std::string m_buffer;
public:
void Log(const XCEngine::Debug::LogEntry& entry) override {
m_buffer += entry.message.CStr();
m_buffer += "\n";
}
void Flush() override {
// 将缓冲区数据写入目标
writeToDestination(m_buffer);
m_buffer.clear();
}
};
```
## 相关文档
- [ILogSink 总览](ilogsink.md) - 返回类总览

14
docs/api/debug/debug-ilogsink.md → docs/api/debug/ilogsink/ilogsink.md
View File

@@ -14,8 +14,8 @@
| 方法 | 描述 |
|------|------|
| `virtual void Log(const LogEntry& entry) = 0` | 输出单条日志 |
| `virtual void Flush() = 0` | 刷新缓冲区，确保日志写入 |
| `virtual void Log(const LogEntry& entry) = 0` | [输出单条日志](log.md) |
| `virtual void Flush() = 0` | [刷新缓冲区，确保日志写入](flush.md) |
## 使用示例
@@ -23,7 +23,6 @@
class CustomLogSink : public ILogSink {
public:
void Log(const LogEntry& entry) override {
// 自定义日志输出逻辑
printf("[%s] %s: %s\n",
LogLevelToString(entry.level),
LogCategoryToString(entry.category),
@@ -31,17 +30,16 @@ public:
}
void Flush() override {
// 刷新缓冲区
fflush(stdout);
}
};
// 注册自定义 Sink
Logger::Get().AddSink(std::make_unique<CustomLogSink>());
```
## 相关文档
- [Logger](./debug-logger.md) - 日志记录器
- [ConsoleLogSink](./debug-consolelogsink.md) - 控制台输出
- [FileLogSink](./debug-filelogsink.md) - 文件输出
- [Debug 模块总览](../debug.md) - 返回模块总览
- [Logger](../logger/logger.md) - 日志记录器
- [ConsoleLogSink](../consolelogsink/consolelogsink.md) - 控制台输出
- [FileLogSink](../filelogsink/filelogsink.md) - 文件输出

29
docs/api/debug/ilogsink/log.md Normal file
View File

@@ -0,0 +1,29 @@
# ILogSink::Log
```cpp
virtual void Log(const LogEntry& entry) = 0
```
输出单条日志到目标介质。`Logger` 在每次日志记录时调用此方法，将包含完整日志信息的 `LogEntry` 传入。派生类需要实现具体的输出逻辑。
**参数：**
- `entry` - 日志条目，包含级别、分类、消息、时间戳、线程 ID 等完整信息
**复杂度：** O(1)
**示例：**
```cpp
class NetworkLogSink : public XCEngine::Debug::ILogSink {
public:
void Log(const XCEngine::Debug::LogEntry& entry) override {
// 将日志发送到远程服务器
sendToServer(entry.message.CStr());
}
void Flush() override { }
};
```
## 相关文档
- [ILogSink 总览](ilogsink.md) - 返回类总览

8
docs/api/debug/debug-logcategory.md → docs/api/debug/logcategory/logcategory.md
View File

@@ -29,18 +29,16 @@
| 函数 | 描述 |
|------|------|
| `const char* LogCategoryToString(LogCategory category)` | 将日志分类转换为字符串 |
| `const char* LogCategoryToString(LogCategory category)` | [将日志分类转换为字符串](logcategorytostring.md) |
## 使用示例
```cpp
// 禁用网络日志
Logger::Get().SetCategoryEnabled(LogCategory::Network, false);
// 输出分类日志
XE_LOG(LogCategory::Rendering, LogLevel::Info, "Draw call submitted");
```
## 相关文档
- [Logger](./debug-logger.md) - 日志记录器
- [Debug 模块总览](../debug.md) - 返回模块总览
- [Logger](../logger/logger.md) - 日志记录器

28
docs/api/debug/logcategory/logcategorytostring.md Normal file
View File

@@ -0,0 +1,28 @@
# LogCategoryToString
```cpp
const char* LogCategoryToString(LogCategory category)
```
将 `LogCategory` 枚举值转换为可读字符串。
**参数：**
- `category` - 日志分类
**返回：** 对应分类的字符串（"General", "Rendering", "Physics" 等）
**复杂度：** O(1)
**示例：**
```cpp
#include <XCEngine/Debug/LogCategory.h>
XCEngine::Debug::LogCategory cat = XCEngine::Debug::LogCategory::Rendering;
const char* str = XCEngine::Debug::LogCategoryToString(cat);
// str == "Rendering"
```
## 相关文档
- [LogCategory 总览](logcategory.md) - 返回类总览

9
docs/api/debug/debug-logentry.md → docs/api/debug/logentry/logentry.md
View File

@@ -20,13 +20,12 @@
| `file` | `Containers::String` | 源代码文件路径 |
| `line` | `int32_t` | 源代码行号 |
| `function` | `Containers::String` | 函数名称 |
| `timestamp` | `uint64_t` | 时间戳（毫秒） |
| `timestamp` | `uint64_t` | 时间戳（秒，Unix 时间戳） |
| `threadId` | `uint32_t` | 线程 ID |
## 使用示例
```cpp
// 实现自定义 Sink 时访问 LogEntry
class MySink : public ILogSink {
public:
void Log(const LogEntry& entry) override {
@@ -37,12 +36,12 @@ public:
LogLevelToString(entry.level),
entry.message.CStr());
}
void Flush() override { }
};
```
## 相关文档
- [ILogSink](./debug-ilogsink.md) - 日志输出接口
- [Logger](./debug-logger.md) - 日志记录器
- [Debug 模块总览](../debug.md) - 返回模块总览
- [ILogSink](../ilogsink/ilogsink.md) - 日志输出接口
- [Logger](../logger/logger.md) - 日志记录器

27
docs/api/debug/logger/addsink.md Normal file
View File

@@ -0,0 +1,27 @@
# Logger::AddSink
```cpp
void AddSink(std::unique_ptr<ILogSink> sink)
```
向日志系统添加一个输出目标（Sink）。Logger 持有 Sink 的所有权，传入的 `unique_ptr` 被移动到内部容器中。每次日志记录时，所有已注册的 Sink 的 `Log` 方法都会被调用。
**参数：**
- `sink` - 要添加的日志输出目标，使用 `std::unique_ptr` 包装
**复杂度：** O(1)
**示例：**
```cpp
#include <XCEngine/Debug/Logger.h>
XCEngine::Debug::Logger::Get().Initialize();
XCEngine::Debug::Logger::Get().AddSink(std::make_unique<XCEngine::Debug::ConsoleLogSink>());
XCEngine::Debug::Logger::Get().AddSink(std::make_unique<XCEngine::Debug::FileLogSink>("app.log"));
```
## 相关文档
- [Logger 总览](logger.md) - 返回类总览
- [ILogSink](../ilogsink/ilogsink.md) - 日志输出接口

30
docs/api/debug/logger/debug.md Normal file
View File

@@ -0,0 +1,30 @@
# Logger::Debug
```cpp
void Debug(LogCategory category, const Containers::String& message)
```
记录一条 Debug（1 级）日志。Debug 级别用于一般调试信息，比 Verbose 简洁但比 Info 详细。
**参数：**
- `category` - 日志分类
- `message` - 日志消息内容
**返回：** 无
**复杂度：** O(n)，n 为注册的 Sink 数量
**示例：**
```cpp
#include <XCEngine/Debug/Logger.h>
XCEngine::Debug::Logger::Get().Debug(
XCEngine::Debug::LogCategory::Rendering,
"Draw call batch size: 512"
);
```
## 相关文档
- [Logger 总览](logger.md) - 返回类总览

30
docs/api/debug/logger/error.md Normal file
View File

@@ -0,0 +1,30 @@
# Logger::Error
```cpp
void Error(LogCategory category, const Containers::String& message)
```
记录一条 Error（4 级）日志。Error 级别用于表示程序执行中发生的错误，如文件读取失败、网络连接中断等。程序通常可以继续运行但功能可能受限。
**参数：**
- `category` - 日志分类
- `message` - 日志消息内容
**返回：** 无
**复杂度：** O(n)，n 为注册的 Sink 数量
**示例：**
```cpp
#include <XCEngine/Debug/Logger.h>
XCEngine::Debug::Logger::Get().Error(
XCEngine::Debug::LogCategory::Network,
"Failed to connect to game server"
);
```
## 相关文档
- [Logger 总览](logger.md) - 返回类总览

30
docs/api/debug/logger/fatal.md Normal file
View File

@@ -0,0 +1,30 @@
# Logger::Fatal
```cpp
void Fatal(LogCategory category, const Containers::String& message)
```
记录一条 Fatal（5 级）日志。Fatal 级别用于表示不可恢复的严重错误，通常意味着程序即将终止。此方法可能在记录日志后触发程序中断。
**参数：**
- `category` - 日志分类
- `message` - 日志消息内容
**返回：** 无
**复杂度：** O(n)，n 为注册的 Sink 数量
**示例：**
```cpp
#include <XCEngine/Debug/Logger.h>
XCEngine::Debug::Logger::Get().Fatal(
XCEngine::Debug::LogCategory::General,
"Out of memory - cannot continue"
);
```
## 相关文档
- [Logger 总览](logger.md) - 返回类总览

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

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

30
docs/api/debug/logger/info.md Normal file
View File

@@ -0,0 +1,30 @@
# Logger::Info
```cpp
void Info(LogCategory category, const Containers::String& message)
```
记录一条 Info（2 级）日志。Info 级别用于一般性信息，如启动提示、配置加载等用户可见的正常运行消息。
**参数：**
- `category` - 日志分类
- `message` - 日志消息内容
**返回：** 无
**复杂度：** O(n)，n 为注册的 Sink 数量
**示例：**
```cpp
#include <XCEngine/Debug/Logger.h>
XCEngine::Debug::Logger::Get().Info(
XCEngine::Debug::LogCategory::General,
"Application initialized successfully"
);
```
## 相关文档
- [Logger 总览](logger.md) - 返回类总览

28
docs/api/debug/logger/initialize.md Normal file
View File

@@ -0,0 +1,28 @@
# Logger::Initialize
```cpp
void Initialize()
```
初始化日志系统。在首次使用日志功能前必须调用。初始化内部状态标志，确保日志系统已准备好工作。
**注意：** 默认最小日志级别为 `Verbose`，所有日志分类默认启用，这些是类成员变量的默认值，不需要在此方法中设置。
**复杂度：** O(1)
**示例：**
```cpp
#include <XCEngine/Debug/Logger.h>
int main() {
XCEngine::Debug::Logger::Get().Initialize();
XCEngine::Debug::Logger::Get().AddSink(std::make_unique<XCEngine::Debug::ConsoleLogSink>());
XCEngine::Debug::Logger::Get().Info(XCEngine::Debug::LogCategory::General, "Application started");
return 0;
}
```
## 相关文档
- [Logger 总览](logger.md) - 返回类总览

45
docs/api/debug/logger/log.md Normal file
View File

@@ -0,0 +1,45 @@
# Logger::Log
```cpp
void Log(LogLevel level, LogCategory category,
const Containers::String& message, const char* file = nullptr,
int32_t line = 0, const char* function = nullptr)
```
通用日志记录方法。根据设置的最小日志级别和分类开关决定是否输出，然后将日志分发给所有已注册的 Sink。如果日志级别低于最小级别或分类被禁用，则不输出。
**参数：**
- `level` - 日志级别（Verbose, Debug, Info, Warning, Error, Fatal）
- `category` - 日志分类（General, Rendering, Physics 等）
- `message` - 日志消息内容
- `file` - 源代码文件路径（可选，默认 nullptr）
- `line` - 源代码行号（可选，默认 0）
- `function` - 函数名称（可选，默认 nullptr）
**返回：** 无
**复杂度：** O(n)，n 为注册的 Sink 数量
**示例：**
```cpp
#include <XCEngine/Debug/Logger.h>
XCEngine::Debug::Logger::Get().Log(
XCEngine::Debug::LogLevel::Error,
XCEngine::Debug::LogCategory::FileSystem,
"Failed to open config file",
__FILE__,
__LINE__,
__FUNCTION__
);
// 推荐使用 XE_LOG 宏自动填充位置信息
XE_LOG(XCEngine::Debug::LogCategory::General, XCEngine::Debug::LogLevel::Info, "Initialized");
```
## 相关文档
- [Logger 总览](logger.md) - 返回类总览
- [LogLevel](../loglevel/loglevel.md) - 日志级别枚举
- [LogCategory](../logcategory/logcategory.md) - 日志分类枚举

35
docs/api/debug/debug-logger.md → docs/api/debug/logger/logger.md
View File

@@ -24,34 +24,34 @@
| 方法 | 描述 |
|------|------|
| `void Initialize()` | 初始化日志系统 |
| `void Shutdown()` | 关闭日志系统 |
| `void Initialize()` | [初始化日志系统](initialize.md) |
| `void Shutdown()` | [关闭日志系统](shutdown.md) |
### Sink 管理
| 方法 | 描述 |
|------|------|
| `void AddSink(std::unique_ptr<ILogSink> sink)` | 添加日志输出目标 |
| `void RemoveSink(ILogSink* sink)` | 移除日志输出目标 |
| `void AddSink(std::unique_ptr<ILogSink> sink)` | [添加日志输出目标](addsink.md) |
| `void RemoveSink(ILogSink* sink)` | [移除日志输出目标](removesink.md) |
### 日志记录
| 方法 | 描述 |
|------|------|
| `void Log(LogLevel level, LogCategory category, const Containers::String& message, const char* file = nullptr, int32_t line = 0, const char* function = nullptr)` | 通用日志记录 |
| `void Verbose(LogCategory category, const Containers::String& message)` | Verbose 级别日志 |
| `void Debug(LogCategory category, const Containers::String& message)` | Debug 级别日志 |
| `void Info(LogCategory category, const Containers::String& message)` | Info 级别日志 |
| `void Warning(LogCategory category, const Containers::String& message)` | Warning 级别日志 |
| `void Error(LogCategory category, const Containers::String& message)` | Error 级别日志 |
| `void Fatal(LogCategory category, const Containers::String& message)` | Fatal 级别日志 |
| `void Log(...)` | [通用日志记录](log.md) |
| `void Verbose(...)` | [Verbose 级别日志](verbose.md) |
| `void Debug(...)` | [Debug 级别日志](debug.md) |
| `void Info(...)` | [Info 级别日志](info.md) |
| `void Warning(...)` | [Warning 级别日志](warning.md) |
| `void Error(...)` | [Error 级别日志](error.md) |
| `void Fatal(...)` | [Fatal 级别日志](fatal.md) |
### 配置
| 方法 | 描述 |
|------|------|
| `void SetMinimumLevel(LogLevel level)` | 设置最小日志级别 |
| `void SetCategoryEnabled(LogCategory category, bool enabled)` | 开启/关闭指定分类 |
| `void SetMinimumLevel(...)` | [设置最小日志级别](setminimumlevel.md) |
| `void SetCategoryEnabled(...)` | [开启/关闭指定分类](setcategoryenabled.md) |
## 宏定义
@@ -102,7 +102,8 @@ XE_ASSERT(ptr != nullptr, "Pointer must not be null");
## 相关文档
- [ILogSink](./debug-ilogsink.md) - 日志输出接口
- [ConsoleLogSink](./debug-consolelogsink.md) - 控制台输出
- [FileLogSink](./debug-filelogsink.md) - 文件输出
- [LogLevel](./debug-loglevel.md) - 日志级别枚举
- [Debug 模块总览](../debug.md) - 返回模块总览
- [ILogSink](../ilogsink/ilogsink.md) - 日志输出接口
- [ConsoleLogSink](../consolelogsink/consolelogsink.md) - 控制台输出
- [FileLogSink](../filelogsink/filelogsink.md) - 文件输出
- [LogLevel](../loglevel/loglevel.md) - 日志级别枚举

29
docs/api/debug/logger/removesink.md Normal file
View File

@@ -0,0 +1,29 @@
# Logger::RemoveSink
```cpp
void RemoveSink(ILogSink* sink)
```
从日志系统移除指定的输出目标。通过指针查找并移除对应的 Sink，Logger 不再向该目标发送日志。
**参数：**
- `sink` - 要移除的日志输出目标指针
**复杂度：** O(n)，n 为注册的 Sink 数量
**示例：**
```cpp
#include <XCEngine/Debug/Logger.h>
auto fileSink = std::make_unique<XCEngine::Debug::FileLogSink>("app.log");
XCEngine::Debug::FileLogSink* rawPtr = fileSink.get();
XCEngine::Debug::Logger::Get().AddSink(std::move(fileSink));
// 稍后移除
XCEngine::Debug::Logger::Get().RemoveSink(rawPtr);
```
## 相关文档
- [Logger 总览](logger.md) - 返回类总览
- [ILogSink](../ilogsink/ilogsink.md) - 日志输出接口

36
docs/api/debug/logger/setcategoryenabled.md Normal file
View File

@@ -0,0 +1,36 @@
# Logger::SetCategoryEnabled
```cpp
void SetCategoryEnabled(LogCategory category, bool enabled)
```
启用或禁用指定分类的日志输出。当分类被禁用时，该分类的所有日志都不会分发给 Sink，但级别过滤仍然适用。
**参数：**
- `category` - 要设置的日志分类
- `enabled` - true 表示启用，false 表示禁用
**复杂度：** O(1)
**示例：**
```cpp
#include <XCEngine/Debug/Logger.h>
// 禁用网络模块日志（减少日志噪音）
XCEngine::Debug::Logger::Get().SetCategoryEnabled(
XCEngine::Debug::LogCategory::Network,
false
);
// 稍后重新启用
XCEngine::Debug::Logger::Get().SetCategoryEnabled(
XCEngine::Debug::LogCategory::Network,
true
);
```
## 相关文档
- [Logger 总览](logger.md) - 返回类总览
- [LogCategory](../logcategory/logcategory.md) - 日志分类枚举

30
docs/api/debug/logger/setminimumlevel.md Normal file
View File

@@ -0,0 +1,30 @@
# Logger::SetMinimumLevel
```cpp
void SetMinimumLevel(LogLevel level)
```
设置日志系统的最小输出级别。所有低于该级别的日志将被过滤，不会分发给任何 Sink。
**参数：**
- `level` - 最小日志级别
**复杂度：** O(1)
**示例：**
```cpp
#include <XCEngine/Debug/Logger.h>
// 只输出 Warning 及以上级别的日志
XCEngine::Debug::Logger::Get().SetMinimumLevel(XCEngine::Debug::LogLevel::Warning);
// Verbose 和 Debug 级别的日志将被过滤
XCEngine::Debug::Logger::Get().Verbose(XCEngine::Debug::LogCategory::General, "This will not be logged");
XCEngine::Debug::Logger::Get().Warning(XCEngine::Debug::LogCategory::General, "This will be logged");
```
## 相关文档
- [Logger 总览](logger.md) - 返回类总览
- [LogLevel](../loglevel/loglevel.md) - 日志级别枚举

26
docs/api/debug/logger/shutdown.md Normal file
View File

@@ -0,0 +1,26 @@
# Logger::Shutdown
```cpp
void Shutdown()
```
关闭日志系统。移除所有注册的 Sink，刷新缓冲区并重置内部状态。在程序退出前调用，确保所有日志数据已写入输出目标。
**复杂度：** O(n)，n 为注册的 Sink 数量
**示例：**
```cpp
#include <XCEngine/Debug/Logger.h>
int main() {
XCEngine::Debug::Logger::Get().Initialize();
// ... 应用逻辑 ...
XCEngine::Debug::Logger::Get().Shutdown();
return 0;
}
```
## 相关文档
- [Logger 总览](logger.md) - 返回类总览

30
docs/api/debug/logger/verbose.md Normal file
View File

@@ -0,0 +1,30 @@
# Logger::Verbose
```cpp
void Verbose(LogCategory category, const Containers::String& message)
```
记录一条 Verbose（0 级）日志。Verbose 是最详细的日志级别，用于输出大量调试细节。
**参数：**
- `category` - 日志分类
- `message` - 日志消息内容
**返回：** 无
**复杂度：** O(n)，n 为注册的 Sink 数量
**示例：**
```cpp
#include <XCEngine/Debug/Logger.h>
XCEngine::Debug::Logger::Get().Verbose(
XCEngine::Debug::LogCategory::Memory,
"Memory pool fragmentation: 12.5%"
);
```
## 相关文档
- [Logger 总览](logger.md) - 返回类总览

30
docs/api/debug/logger/warning.md Normal file
View File

@@ -0,0 +1,30 @@
# Logger::Warning
```cpp
void Warning(LogCategory category, const Containers::String& message)
```
记录一条 Warning（3 级）日志。Warning 级别用于指示潜在问题但程序仍可继续运行的情况，如资源即将耗尽、配置值超出建议范围等。
**参数：**
- `category` - 日志分类
- `message` - 日志消息内容
**返回：** 无
**复杂度：** O(n)，n 为注册的 Sink 数量
**示例：**
```cpp
#include <XCEngine/Debug/Logger.h>
XCEngine::Debug::Logger::Get().Warning(
XCEngine::Debug::LogCategory::Memory,
"Memory usage exceeds 80% of available heap"
);
```
## 相关文档
- [Logger 总览](logger.md) - 返回类总览

6
docs/api/debug/debug-loglevel.md → docs/api/debug/loglevel/loglevel.md
View File

@@ -25,16 +25,16 @@
| 函数 | 描述 |
|------|------|
| `const char* LogLevelToString(LogLevel level)` | 将日志级别转换为字符串 |
| `const char* LogLevelToString(LogLevel level)` | [将日志级别转换为字符串](logleveltostring.md) |
## 使用示例
```cpp
// 设置最小日志级别
Logger::Get().SetMinimumLevel(LogLevel::Warning);
// 只有 Warning、Error、Fatal 级别的日志会被输出
```
## 相关文档
- [Logger](./debug-logger.md) - 日志记录器
- [Debug 模块总览](../debug.md) - 返回模块总览
- [Logger](../logger/logger.md) - 日志记录器

28
docs/api/debug/loglevel/logleveltostring.md Normal file
View File

@@ -0,0 +1,28 @@
# LogLevelToString
```cpp
const char* LogLevelToString(LogLevel level)
```
将 `LogLevel` 枚举值转换为可读字符串。
**参数：**
- `level` - 日志级别
**返回：** 对应级别的字符串（"VERBOSE", "DEBUG", "INFO", "WARNING", "ERROR", "FATAL"）
**复杂度：** O(1)
**示例：**
```cpp
#include <XCEngine/Debug/LogLevel.h>
XCEngine::Debug::LogLevel level = XCEngine::Debug::LogLevel::Error;
const char* str = XCEngine::Debug::LogLevelToString(level);
// str == "Error"
```
## 相关文档
- [LogLevel 总览](loglevel.md) - 返回类总览

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) - 返回类总览

27
docs/api/debug/debug-profiler.md → docs/api/debug/profiler/profiler.md
View File

@@ -22,35 +22,35 @@
| 方法 | 描述 |
|------|------|
| `void Initialize()` | 初始化性能分析器 |
| `void Shutdown()` | 关闭性能分析器 |
| `void Initialize()` | [初始化性能分析器](initialize.md) |
| `void Shutdown()` | [关闭性能分析器](shutdown.md) |
### 性能测量
| 方法 | 描述 |
|------|------|
| `void BeginProfile(const char* name)` | 开始一个性能分析块 |
| `void EndProfile()` | 结束当前性能分析块 |
| `void BeginProfile(const char* name)` | [开始一个性能分析块](beginprofile.md) |
| `void EndProfile()` | [结束当前性能分析块](endprofile.md) |
### 帧管理
| 方法 | 描述 |
|------|------|
| `void BeginFrame()` | 开始一帧的分析 |
| `void EndFrame()` | 结束一帧的分析 |
| `void BeginFrame()` | [开始一帧的分析](beginframe.md) |
| `void EndFrame()` | [结束一帧的分析](endframe.md) |
### 事件标记
| 方法 | 描述 |
|------|------|
| `void MarkEvent(const char* name, uint64_t timestamp, uint32_t threadId)` | 标记一个事件点 |
| `void SetMarker(const char* name, uint32_t color)` | 设置帧标记 |
| `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 格式 |
| `void ExportChromeTracing(const Containers::String& filePath)` | [导出为 Chrome Tracing JSON 格式](exportchrometracing.md) |
## 宏定义
@@ -81,10 +81,8 @@
## 使用示例
```cpp
// 初始化
Profiler::Get().Initialize();
// 使用宏自动管理生命周期
void RenderFrame() {
XE_PROFILE_FUNCTION();
@@ -101,17 +99,14 @@ void RenderFrame() {
}
}
// 帧管理
Profiler::Get().BeginFrame();
// ... 渲染帧 ...
Profiler::Get().EndFrame();
// 导出 Chrome Tracing 格式
Profiler::Get().ExportChromeTracing("profile.json");
Profiler::Get().Shutdown();
```
## 相关文档
- [Logger](./debug-logger.md) - 日志记录器
- [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) - 返回类总览