refactor: reorganize docs into plan/ and add skills/
This commit is contained in:
77
docs/api/core/core-event.md
Normal file
77
docs/api/core/core-event.md
Normal file
@@ -0,0 +1,77 @@
|
||||
# Event
|
||||
|
||||
**命名空间**: `XCEngine::Core`
|
||||
|
||||
**类型**: `class` (template)
|
||||
|
||||
**描述**: 事件系统模板类，提供类型安全的多订阅者事件/委托系统。
|
||||
|
||||
## 概述
|
||||
|
||||
`Event<Args...>` 是一个类型安全的事件发布-订阅系统。它支持多个回调订阅、退订和线程安全的调用。非常适合用于游戏引擎中的事件驱动通信。
|
||||
|
||||
## 模板参数
|
||||
|
||||
| 参数 | 描述 |
|
||||
|------|------|
|
||||
| `Args...` | 事件回调的参数类型 |
|
||||
|
||||
## 类型别名
|
||||
|
||||
| 别名 | 类型 | 描述 |
|
||||
|------|------|------|
|
||||
| `Callback` | `std::function<void(Args...)>` | 回调函数类型 |
|
||||
| `Listener` | `std::pair<uint64_t, Callback>` | 监听器条目 |
|
||||
| `Iterator` | `std::vector<Listener>::iterator` | 迭代器类型 |
|
||||
|
||||
## 公共方法
|
||||
|
||||
### 订阅/退订
|
||||
|
||||
| 方法 | 描述 |
|
||||
|------|------|
|
||||
| `uint64_t Subscribe(Callback callback)` | 订阅事件，返回订阅 ID |
|
||||
| `void Unsubscribe(uint64_t id)` | 退订事件（延迟生效） |
|
||||
| `void ProcessUnsubscribes()` | 处理积压的退订请求 |
|
||||
| `void Clear()` | 清空所有订阅 |
|
||||
|
||||
### 调用
|
||||
|
||||
| 方法 | 描述 |
|
||||
|------|------|
|
||||
| `void Invoke(Args... args)` | 调用所有订阅的回调 |
|
||||
|
||||
### 迭代
|
||||
|
||||
| 方法 | 描述 |
|
||||
|------|------|
|
||||
| `Iterator begin()` | 获取开始迭代器 |
|
||||
| `Iterator end()` | 获取结束迭代器 |
|
||||
|
||||
## 使用示例
|
||||
|
||||
```cpp
|
||||
// 定义事件（无参数）
|
||||
Event<> frameStartEvent;
|
||||
|
||||
// 定义事件（带参数）
|
||||
Event<int, float> damageEvent;
|
||||
|
||||
// 订阅
|
||||
uint64_t id = damageEvent.Subscribe([](int damage, float time) {
|
||||
printf("Damage: %d at time %f\n", damage, time);
|
||||
});
|
||||
|
||||
// 触发事件
|
||||
damageEvent.Invoke(100, 3.14f);
|
||||
|
||||
// 退订
|
||||
damageEvent.Unsubscribe(id);
|
||||
|
||||
// 清空
|
||||
frameStartEvent.Clear();
|
||||
```
|
||||
|
||||
## 相关文档
|
||||
|
||||
- [Core 模块概览](./core-overview.md) - Core 模块总览
|
||||
75
docs/api/core/core-filewriter.md
Normal file
75
docs/api/core/core-filewriter.md
Normal file
@@ -0,0 +1,75 @@
|
||||
# FileWriter
|
||||
|
||||
**命名空间**: `XCEngine::Core`
|
||||
|
||||
**类型**: `class`
|
||||
|
||||
**描述**: 文件写入工具类，提供简单的文件写入操作封装。
|
||||
|
||||
## 概述
|
||||
|
||||
`FileWriter` 是一个轻量级的文件写入工具，封装了 `FILE*` 接口，提供便捷的字符串和二进制数据写入功能。它支持追加模式和自动资源管理（RAII）。
|
||||
|
||||
## 公共方法
|
||||
|
||||
### 构造/析构
|
||||
|
||||
| 方法 | 描述 |
|
||||
|------|------|
|
||||
| `FileWriter()` | 默认构造（不打开文件） |
|
||||
| `FileWriter(const char* filePath, bool append = false)` | 构造并打开文件 |
|
||||
| `~FileWriter()` | 析构函数，自动关闭文件 |
|
||||
|
||||
### 文件操作
|
||||
|
||||
| 方法 | 描述 |
|
||||
|------|------|
|
||||
| `bool Open(const char* filePath, bool append = false)` | 打开文件，append=true 时为追加模式 |
|
||||
| `void Close()` | 关闭文件 |
|
||||
| `bool IsOpen() const` | 检查文件是否已打开 |
|
||||
|
||||
### 数据写入
|
||||
|
||||
| 方法 | 描述 |
|
||||
|------|------|
|
||||
| `bool Write(const char* data, size_t length)` | 写入指定长度的字符串 |
|
||||
| `bool Write(const Containers::String& str)` | 写入 String 内容 |
|
||||
| `bool Flush()` | 刷新缓冲区，确保数据写入磁盘 |
|
||||
|
||||
## 使用示例
|
||||
|
||||
```cpp
|
||||
#include <XCEngine/Core/FileWriter.h>
|
||||
|
||||
// 方式1：构造时打开
|
||||
FileWriter writer("output.txt", false);
|
||||
if (writer.IsOpen()) {
|
||||
writer.Write("Hello, World!\n");
|
||||
writer.Write("Line 2\n");
|
||||
writer.Flush();
|
||||
}
|
||||
|
||||
// 方式2：先构造再打开
|
||||
FileWriter writer2;
|
||||
if (writer2.Open("log.txt")) {
|
||||
writer2.Write("Application started\n");
|
||||
writer2.Close();
|
||||
}
|
||||
|
||||
// 追加模式
|
||||
FileWriter appendWriter("log.txt", true);
|
||||
if (appendWriter.IsOpen()) {
|
||||
appendWriter.Write("Another log entry\n");
|
||||
appendWriter.Flush();
|
||||
}
|
||||
|
||||
// 使用 String 写入
|
||||
Containers::String content = "Content written from String";
|
||||
FileWriter writer3("data.txt");
|
||||
writer3.Write(content);
|
||||
```
|
||||
|
||||
## 相关文档
|
||||
|
||||
- [Logger](../debug/debug-logger.md) - 日志系统
|
||||
- [FileLogSink](../debug/debug-filelogsink.md) - 文件日志输出
|
||||
94
docs/api/core/core-overview.md
Normal file
94
docs/api/core/core-overview.md
Normal file
@@ -0,0 +1,94 @@
|
||||
# Core 模块概览
|
||||
|
||||
**命名空间**: `XCEngine::Core`
|
||||
|
||||
**类型**: `module`
|
||||
|
||||
**描述**: XCEngine 的核心基础模块，提供类型别名、智能指针、事件系统等基础功能。
|
||||
|
||||
## 概述
|
||||
|
||||
Core 模块包含了引擎所需的基础类型和工具，是其他所有模块的依赖基础。
|
||||
|
||||
## 模块内容
|
||||
|
||||
### 类型
|
||||
|
||||
| 组件 | 文件 | 描述 |
|
||||
|------|------|------|
|
||||
| [Types](./core-types.md) | `Types.h` | 类型别名定义 |
|
||||
|
||||
### 智能指针
|
||||
|
||||
| 组件 | 文件 | 描述 |
|
||||
|------|------|------|
|
||||
| [SmartPtr](./core-smartptr.md) | `SmartPtr.h` | 智能指针别名和工厂函数 |
|
||||
| [RefCounted](./core-refcounted.md) | `RefCounted.h` | 引用计数基类 |
|
||||
|
||||
### 事件系统
|
||||
|
||||
| 组件 | 文件 | 描述 |
|
||||
|------|------|------|
|
||||
| [Event](./core-event.md) | `Event.h` | 事件系统模板 |
|
||||
|
||||
### 文件操作
|
||||
|
||||
| 组件 | 文件 | 描述 |
|
||||
|------|------|------|
|
||||
| [FileWriter](./core-filewriter.md) | `FileWriter.h` | 文件写入工具 |
|
||||
|
||||
## 类型别名
|
||||
|
||||
```cpp
|
||||
using int8 = int8_t;
|
||||
using int16 = int16_t;
|
||||
using int32 = int32_t;
|
||||
using int64 = int64_t;
|
||||
using uint8 = uint8_t;
|
||||
using uint16 = uint16_t;
|
||||
using uint32 = uint32_t;
|
||||
using uint64 = uint64_t;
|
||||
using byte = uint8_t;
|
||||
```
|
||||
|
||||
## 智能指针别名
|
||||
|
||||
```cpp
|
||||
template<typename T>
|
||||
using Ref = std::shared_ptr<T>;
|
||||
|
||||
template<typename T>
|
||||
using UniqueRef = std::unique_ptr<T>;
|
||||
|
||||
template<typename T, typename... Args>
|
||||
Ref<T> MakeRef(Args&&... args);
|
||||
|
||||
template<typename T, typename... Args>
|
||||
UniqueRef<T> MakeUnique(Args&&... args);
|
||||
```
|
||||
|
||||
## 使用示例
|
||||
|
||||
```cpp
|
||||
#include <XCEngine/Core/Core.h>
|
||||
|
||||
// 使用类型别名
|
||||
Core::uint32 value = 100;
|
||||
Core::byte data[4];
|
||||
|
||||
// 使用智能指针
|
||||
auto ref = MakeRef<MyClass>();
|
||||
auto unique = MakeUnique<MyClass>();
|
||||
|
||||
// 使用事件系统
|
||||
Event<int, float> myEvent;
|
||||
myEvent.Subscribe([](int a, float b) {
|
||||
printf("Event: %d, %f\n", a, b);
|
||||
});
|
||||
myEvent.Invoke(42, 3.14f);
|
||||
```
|
||||
|
||||
## 相关文档
|
||||
|
||||
- [Containers 模块](../containers/container-overview.md) - 容器类型
|
||||
- [Memory 模块](../memory/memory-overview.md) - 内存管理
|
||||
50
docs/api/core/core-refcounted.md
Normal file
50
docs/api/core/core-refcounted.md
Normal file
@@ -0,0 +1,50 @@
|
||||
# RefCounted
|
||||
|
||||
**命名空间**: `XCEngine::Core`
|
||||
|
||||
**类型**: `class`
|
||||
|
||||
**描述**: 引用计数基类，提供线程安全的引用计数生命周期管理。
|
||||
|
||||
## 概述
|
||||
|
||||
`RefCounted` 是一个简单的引用计数基类。当引用计数归零时，对象会自动删除。它提供了 `AddRef` 和 `Release` 方法，线程安全地管理引用计数。
|
||||
|
||||
## 公共方法
|
||||
|
||||
### 构造/析构
|
||||
|
||||
| 方法 | 描述 |
|
||||
|------|------|
|
||||
| `RefCounted()` | 构造函数，初始引用计数为 1 |
|
||||
| `virtual ~RefCounted()` | 虚析构函数 |
|
||||
|
||||
### 引用计数
|
||||
|
||||
| 方法 | 描述 |
|
||||
|------|------|
|
||||
| `void AddRef()` | 增加引用计数 |
|
||||
| `void Release()` | 减少引用计数（归零时自动 delete this） |
|
||||
| `uint32_t GetRefCount() const` | 获取当前引用计数 |
|
||||
|
||||
## 使用示例
|
||||
|
||||
```cpp
|
||||
class MyObject : public RefCounted {
|
||||
public:
|
||||
MyObject() { /* ... */ }
|
||||
~MyObject() { /* ... */ }
|
||||
|
||||
void DoSomething() { /* ... */ }
|
||||
};
|
||||
|
||||
// 使用
|
||||
MyObject* obj = new MyObject(); // refCount = 1
|
||||
obj->AddRef(); // refCount = 2
|
||||
obj->Release(); // refCount = 1
|
||||
obj->Release(); // refCount = 0, 自动 delete
|
||||
```
|
||||
|
||||
## 相关文档
|
||||
|
||||
- [SmartPtr](./core-smartptr.md) - 智能指针
|
||||
54
docs/api/core/core-smartptr.md
Normal file
54
docs/api/core/core-smartptr.md
Normal file
@@ -0,0 +1,54 @@
|
||||
# SmartPtr
|
||||
|
||||
**命名空间**: `XCEngine::Core`
|
||||
|
||||
**类型**: `header-only`
|
||||
|
||||
**描述**: 智能指针类型别名和工厂函数，提供 `std::shared_ptr` 和 `std::unique_ptr` 的简化接口。
|
||||
|
||||
## 概述
|
||||
|
||||
`Core::SmartPtr` 提供了 `std::shared_ptr` 和 `std::unique_ptr` 的类型别名和工厂函数，使智能指针的使用更加简洁。
|
||||
|
||||
## 类型别名
|
||||
|
||||
| 别名 | 底层类型 | 描述 |
|
||||
|------|----------|------|
|
||||
| `Core::Ref<T>` | `std::shared_ptr<T>` | 共享引用智能指针 |
|
||||
| `Core::UniqueRef<T>` | `std::unique_ptr<T>` | 独占所有权的智能指针 |
|
||||
|
||||
## 工厂函数
|
||||
|
||||
| 函数 | 返回值 | 描述 |
|
||||
|------|--------|------|
|
||||
| `Core::MakeRef<T>(Args&&... args)` | `Ref<T>` | 创建共享指针 |
|
||||
| `Core::MakeUnique<T>(Args&&... args)` | `UniqueRef<T>` | 创建独占指针 |
|
||||
|
||||
## 使用示例
|
||||
|
||||
```cpp
|
||||
#include <XCEngine/Core/Core.h>
|
||||
|
||||
// 使用 Ref（共享指针）
|
||||
Core::Ref<MyClass> ref = Core::MakeRef<MyClass>(arg1, arg2);
|
||||
|
||||
// 使用 UniqueRef（独占指针）
|
||||
Core::UniqueRef<MyClass> unique = Core::MakeUnique<MyClass>();
|
||||
|
||||
// 传递所有权
|
||||
Core::Ref<MyClass> ref2 = ref; // 引用计数 +1
|
||||
|
||||
// 检查有效性
|
||||
if (ref) {
|
||||
ref->DoSomething();
|
||||
}
|
||||
|
||||
// 自定义删除器
|
||||
Core::UniqueRef<FILE, decltype(&fclose)>
|
||||
file(fopen("test.txt", "r"), &fclose);
|
||||
```
|
||||
|
||||
## 相关文档
|
||||
|
||||
- [RefCounted](./core-refcounted.md) - 引用计数基类
|
||||
- [Types](./core-types.md) - 类型别名
|
||||
49
docs/api/core/core-types.md
Normal file
49
docs/api/core/core-types.md
Normal file
@@ -0,0 +1,49 @@
|
||||
# Types
|
||||
|
||||
**命名空间**: `XCEngine::Core`
|
||||
|
||||
**类型**: `header` (type aliases)
|
||||
|
||||
**头文件**: `XCEngine/Core/Types.h`
|
||||
|
||||
**描述**: 基础类型别名定义，提供跨平台一致的基础类型名称。
|
||||
|
||||
## 概述
|
||||
|
||||
`Types.h` 定义了一组类型别名，简化了标准库类型的使用，并提供跨平台一致性。
|
||||
|
||||
## 类型别名
|
||||
|
||||
| 别名 | 实际类型 | 描述 |
|
||||
|------|----------|------|
|
||||
| `int8` | `int8_t` | 8位有符号整数 |
|
||||
| `int16` | `int16_t` | 16位有符号整数 |
|
||||
| `int32` | `int32_t` | 32位有符号整数 |
|
||||
| `int64` | `int64_t` | 64位有符号整数 |
|
||||
| `uint8` | `uint8_t` | 8位无符号整数 |
|
||||
| `uint16` | `uint16_t` | 16位无符号整数 |
|
||||
| `uint32` | `uint32_t` | 32位无符号整数 |
|
||||
| `uint64` | `uint64_t` | 64位无符号整数 |
|
||||
| `byte` | `uint8_t` | 字节类型 |
|
||||
|
||||
## 使用示例
|
||||
|
||||
```cpp
|
||||
#include <XCEngine/Core/Types.h>
|
||||
|
||||
// 使用类型别名
|
||||
Core::int32 count = 100;
|
||||
Core::uint64 id = 1234567890;
|
||||
Core::byte flags = 0xFF;
|
||||
|
||||
// 数组定义
|
||||
Core::uint8 buffer[1024];
|
||||
|
||||
// 函数参数
|
||||
void ProcessData(Core::uint32 size, const Core::int8* data);
|
||||
```
|
||||
|
||||
## 相关文档
|
||||
|
||||
- [SmartPtr](./core-smartptr.md) - 智能指针
|
||||
- [RefCounted](./core-refcounted.md) - 引用计数基类
|
||||
Reference in New Issue
Block a user