docs: rebuild Scene API content
This commit is contained in:
@@ -1,31 +1,35 @@
|
||||
# SceneManager::CreateScene
|
||||
|
||||
创建新对象或资源。
|
||||
创建并登记一个新场景。
|
||||
|
||||
```cpp
|
||||
Scene* CreateScene(const std::string& name);
|
||||
```
|
||||
|
||||
该方法声明于 `XCEngine/Scene/SceneManager.h`，当前页面用于固定 `SceneManager` 类目录下的方法级 canonical 路径。
|
||||
## 行为说明
|
||||
|
||||
**参数：**
|
||||
- `name` - 参数语义详见头文件声明。
|
||||
当前实现会：
|
||||
|
||||
**返回：** `Scene*` - 返回值语义详见头文件声明。
|
||||
1. 构造 `std::make_unique<Scene>(name)`。
|
||||
2. 把场景存入 `m_scenes[name]`。
|
||||
3. 如果当前没有活动场景，则把 `m_activeScene` 设为新场景。
|
||||
4. 触发 [OnSceneLoaded](OnSceneLoaded.md)。
|
||||
|
||||
**示例：**
|
||||
## 参数
|
||||
|
||||
```cpp
|
||||
#include <XCEngine/Scene/SceneManager.h>
|
||||
- `name` - 新场景名称，同时也是 `m_scenes` 的 key。
|
||||
|
||||
void Example() {
|
||||
XCEngine::Components::SceneManager object;
|
||||
// 根据上下文补齐参数后调用 SceneManager::CreateScene(...)。
|
||||
(void)object;
|
||||
}
|
||||
```
|
||||
## 返回值
|
||||
|
||||
- `Scene*` - 新场景的非拥有指针。
|
||||
|
||||
## 当前实现限制
|
||||
|
||||
- 如果同名 key 已存在，旧场景会被替换；先前拿到的裸指针可能失效。
|
||||
- 当它成为第一个活动场景时，当前不会额外触发 [OnActiveSceneChanged](OnActiveSceneChanged.md)。
|
||||
|
||||
## 相关文档
|
||||
|
||||
- [返回类总览](SceneManager.md)
|
||||
- [返回模块目录](../Scene.md)
|
||||
- [返回类型总览](SceneManager.md)
|
||||
- [GetScene](GetScene.md)
|
||||
- [OnSceneLoaded](OnSceneLoaded.md)
|
||||
|
||||
@@ -1,29 +1,23 @@
|
||||
# SceneManager::Get
|
||||
|
||||
获取相关状态或对象。
|
||||
获取全局 `SceneManager` 单例。
|
||||
|
||||
```cpp
|
||||
static SceneManager& Get();
|
||||
```
|
||||
|
||||
该方法声明于 `XCEngine/Scene/SceneManager.h`，当前页面用于固定 `SceneManager` 类目录下的方法级 canonical 路径。
|
||||
## 行为说明
|
||||
|
||||
**参数：** 无。
|
||||
|
||||
**返回：** `SceneManager&` - 返回值语义详见头文件声明。
|
||||
|
||||
**示例：**
|
||||
当前实现通过函数内静态对象返回进程级单例：
|
||||
|
||||
```cpp
|
||||
#include <XCEngine/Scene/SceneManager.h>
|
||||
|
||||
void Example() {
|
||||
auto& instance = XCEngine::Components::SceneManager::Get();
|
||||
(void)instance;
|
||||
}
|
||||
static SceneManager instance;
|
||||
```
|
||||
|
||||
## 返回值
|
||||
|
||||
- `SceneManager&` - 全局场景管理器实例引用。
|
||||
|
||||
## 相关文档
|
||||
|
||||
- [返回类总览](SceneManager.md)
|
||||
- [返回模块目录](../Scene.md)
|
||||
- [返回类型总览](SceneManager.md)
|
||||
|
||||
@@ -1,30 +1,25 @@
|
||||
# SceneManager::GetActiveScene
|
||||
|
||||
获取相关状态或对象。
|
||||
获取当前活动场景。
|
||||
|
||||
```cpp
|
||||
Scene* GetActiveScene() const;
|
||||
```
|
||||
|
||||
该方法声明于 `XCEngine/Scene/SceneManager.h`，当前页面用于固定 `SceneManager` 类目录下的方法级 canonical 路径。
|
||||
## 行为说明
|
||||
|
||||
**参数：** 无。
|
||||
当前头文件内联实现直接返回 `m_activeScene`。
|
||||
|
||||
**返回：** `Scene*` - 返回值语义详见头文件声明。
|
||||
## 返回值
|
||||
|
||||
**示例：**
|
||||
- `Scene*` - 当前活动场景指针；没有活动场景时返回 `nullptr`。
|
||||
|
||||
```cpp
|
||||
#include <XCEngine/Scene/SceneManager.h>
|
||||
## 注意事项
|
||||
|
||||
void Example() {
|
||||
XCEngine::Components::SceneManager object;
|
||||
// 根据上下文补齐参数后调用 SceneManager::GetActiveScene(...)。
|
||||
(void)object;
|
||||
}
|
||||
```
|
||||
- 这是非拥有指针。
|
||||
- 它与 `Scene::IsActive()` 当前不是同一个概念，也不会自动同步。
|
||||
|
||||
## 相关文档
|
||||
|
||||
- [返回类总览](SceneManager.md)
|
||||
- [返回模块目录](../Scene.md)
|
||||
- [返回类型总览](SceneManager.md)
|
||||
- [SetActiveScene](SetActiveScene.md)
|
||||
|
||||
@@ -1,30 +1,24 @@
|
||||
# SceneManager::GetAllScenes
|
||||
|
||||
获取相关状态或对象。
|
||||
获取全部已登记场景。
|
||||
|
||||
```cpp
|
||||
std::vector<Scene*> GetAllScenes() const;
|
||||
```
|
||||
|
||||
该方法声明于 `XCEngine/Scene/SceneManager.h`，当前页面用于固定 `SceneManager` 类目录下的方法级 canonical 路径。
|
||||
## 行为说明
|
||||
|
||||
**参数：** 无。
|
||||
当前实现会遍历 `m_scenes`，把每个 `unique_ptr<Scene>` 的裸指针收集到结果数组中返回。
|
||||
|
||||
**返回：** `std::vector<Scene*>` - 返回值语义详见头文件声明。
|
||||
## 返回值
|
||||
|
||||
**示例：**
|
||||
- `std::vector<Scene*>` - 所有已登记场景的非拥有指针数组。
|
||||
|
||||
```cpp
|
||||
#include <XCEngine/Scene/SceneManager.h>
|
||||
## 注意事项
|
||||
|
||||
void Example() {
|
||||
XCEngine::Components::SceneManager object;
|
||||
// 根据上下文补齐参数后调用 SceneManager::GetAllScenes(...)。
|
||||
(void)object;
|
||||
}
|
||||
```
|
||||
- 返回顺序取决于 `std::unordered_map` 的迭代顺序，不应把它当作稳定顺序。
|
||||
|
||||
## 相关文档
|
||||
|
||||
- [返回类总览](SceneManager.md)
|
||||
- [返回模块目录](../Scene.md)
|
||||
- [返回类型总览](SceneManager.md)
|
||||
- [GetScene](GetScene.md)
|
||||
|
||||
@@ -1,31 +1,29 @@
|
||||
# SceneManager::GetScene
|
||||
|
||||
获取相关状态或对象。
|
||||
按内部 key 获取场景。
|
||||
|
||||
```cpp
|
||||
Scene* GetScene(const std::string& name) const;
|
||||
```
|
||||
|
||||
该方法声明于 `XCEngine/Scene/SceneManager.h`，当前页面用于固定 `SceneManager` 类目录下的方法级 canonical 路径。
|
||||
## 行为说明
|
||||
|
||||
**参数：**
|
||||
- `name` - 参数语义详见头文件声明。
|
||||
当前实现直接用 `name` 在 `m_scenes` 里做哈希表查找。
|
||||
|
||||
**返回：** `Scene*` - 返回值语义详见头文件声明。
|
||||
## 参数
|
||||
|
||||
**示例：**
|
||||
- `name` - 场景 key。
|
||||
|
||||
```cpp
|
||||
#include <XCEngine/Scene/SceneManager.h>
|
||||
## 返回值
|
||||
|
||||
void Example() {
|
||||
XCEngine::Components::SceneManager object;
|
||||
// 根据上下文补齐参数后调用 SceneManager::GetScene(...)。
|
||||
(void)object;
|
||||
}
|
||||
```
|
||||
- `Scene*` - 找到时返回场景指针；找不到时返回 `nullptr`。
|
||||
|
||||
## 注意事项
|
||||
|
||||
- 这个 `name` 对于 [CreateScene](CreateScene.md) 来说是创建时传入的名称。
|
||||
- 对于 [LoadScene](LoadScene.md) 来说，它是文件名 stem，而不一定等于场景内部的 `Scene::GetName()`。
|
||||
|
||||
## 相关文档
|
||||
|
||||
- [返回类总览](SceneManager.md)
|
||||
- [返回模块目录](../Scene.md)
|
||||
- [返回类型总览](SceneManager.md)
|
||||
- [LoadScene](LoadScene.md)
|
||||
|
||||
@@ -1,31 +1,37 @@
|
||||
# SceneManager::LoadScene
|
||||
|
||||
加载资源或数据。
|
||||
从文件加载并登记一个场景。
|
||||
|
||||
```cpp
|
||||
void LoadScene(const std::string& filePath);
|
||||
```
|
||||
|
||||
该方法声明于 `XCEngine/Scene/SceneManager.h`，当前页面用于固定 `SceneManager` 类目录下的方法级 canonical 路径。
|
||||
## 行为说明
|
||||
|
||||
**参数：**
|
||||
- `filePath` - 参数语义详见头文件声明。
|
||||
当前实现会：
|
||||
|
||||
**返回：** `void` - 无返回值。
|
||||
1. 构造一个默认 `Scene`。
|
||||
2. 调用 `scene->Load(filePath)`。
|
||||
3. 从 `filePath` 中提取“文件名去扩展名”的字符串作为 map key。
|
||||
4. 把场景存入 `m_scenes[key]`。
|
||||
5. 触发 [OnSceneLoaded](OnSceneLoaded.md)。
|
||||
|
||||
**示例：**
|
||||
## 参数
|
||||
|
||||
```cpp
|
||||
#include <XCEngine/Scene/SceneManager.h>
|
||||
- `filePath` - 场景文件路径。
|
||||
|
||||
void Example() {
|
||||
XCEngine::Components::SceneManager object;
|
||||
// 根据上下文补齐参数后调用 SceneManager::LoadScene(...)。
|
||||
(void)object;
|
||||
}
|
||||
```
|
||||
## 返回值
|
||||
|
||||
- 无。
|
||||
|
||||
## 当前实现限制
|
||||
|
||||
- 当前不会在首次加载时自动设置 `m_activeScene`。
|
||||
- 如果同 key 场景已存在，旧场景会被替换。
|
||||
- `Scene::GetName()` 可能来自文件内部内容，而 `SceneManager` 保存的 key 来自文件名，两者可能不同。
|
||||
|
||||
## 相关文档
|
||||
|
||||
- [返回类总览](SceneManager.md)
|
||||
- [返回模块目录](../Scene.md)
|
||||
- [返回类型总览](SceneManager.md)
|
||||
- [LoadSceneAsync](LoadSceneAsync.md)
|
||||
- [GetScene](GetScene.md)
|
||||
|
||||
@@ -1,32 +1,33 @@
|
||||
# SceneManager::LoadSceneAsync
|
||||
|
||||
加载资源或数据。
|
||||
异步加载场景。
|
||||
|
||||
```cpp
|
||||
void LoadSceneAsync(const std::string& filePath, std::function<void(Scene*)> callback);
|
||||
```
|
||||
|
||||
该方法声明于 `XCEngine/Scene/SceneManager.h`，当前页面用于固定 `SceneManager` 类目录下的方法级 canonical 路径。
|
||||
## 行为说明
|
||||
|
||||
**参数：**
|
||||
- `filePath` - 参数语义详见头文件声明。
|
||||
- `callback` - 参数语义详见头文件声明。
|
||||
当前实现实际上并没有启动后台任务，而是：
|
||||
|
||||
**返回：** `void` - 无返回值。
|
||||
1. 直接调用 [LoadScene](LoadScene.md)。
|
||||
2. 如果 `callback` 非空，再执行 `callback(GetScene(filePath))`。
|
||||
|
||||
**示例：**
|
||||
## 参数
|
||||
|
||||
```cpp
|
||||
#include <XCEngine/Scene/SceneManager.h>
|
||||
- `filePath` - 场景文件路径。
|
||||
- `callback` - 加载结束后调用的回调。
|
||||
|
||||
void Example() {
|
||||
XCEngine::Components::SceneManager object;
|
||||
// 根据上下文补齐参数后调用 SceneManager::LoadSceneAsync(...)。
|
||||
(void)object;
|
||||
}
|
||||
```
|
||||
## 返回值
|
||||
|
||||
- 无。
|
||||
|
||||
## 当前实现限制
|
||||
|
||||
- 当前完全是同步执行，不是线程化或任务系统驱动的异步加载。
|
||||
- 回调查找使用的是原始 `filePath`，而 [LoadScene](LoadScene.md) 存储使用的是文件名 stem。对于常见的 `assets/scenes/Main.xc` 这类输入，`GetScene(filePath)` 通常会返回 `nullptr`。
|
||||
|
||||
## 相关文档
|
||||
|
||||
- [返回类总览](SceneManager.md)
|
||||
- [返回模块目录](../Scene.md)
|
||||
- [返回类型总览](SceneManager.md)
|
||||
- [LoadScene](LoadScene.md)
|
||||
|
||||
@@ -1,30 +1,26 @@
|
||||
# SceneManager::OnActiveSceneChanged
|
||||
|
||||
公开方法，详见头文件声明。
|
||||
访问活动场景切换事件。
|
||||
|
||||
```cpp
|
||||
Core::Event<Scene*>& OnActiveSceneChanged();
|
||||
```
|
||||
|
||||
该方法声明于 `XCEngine/Scene/SceneManager.h`，当前页面用于固定 `SceneManager` 类目录下的方法级 canonical 路径。
|
||||
## 行为说明
|
||||
|
||||
**参数：** 无。
|
||||
当前头文件内联实现直接返回 `m_onActiveSceneChanged` 的引用。
|
||||
|
||||
**返回：** `Core::Event<Scene*>&` - 返回值语义详见头文件声明。
|
||||
这个事件会在：
|
||||
|
||||
**示例：**
|
||||
- [SetActiveScene](SetActiveScene.md) 真正改变 `m_activeScene` 时触发。
|
||||
- [UnloadScene](UnloadScene.md) 卸载当前活动场景并自动选择新的后备场景时触发。
|
||||
|
||||
```cpp
|
||||
#include <XCEngine/Scene/SceneManager.h>
|
||||
## 返回值
|
||||
|
||||
void Example() {
|
||||
XCEngine::Components::SceneManager object;
|
||||
// 根据上下文补齐参数后调用 SceneManager::OnActiveSceneChanged(...)。
|
||||
(void)object;
|
||||
}
|
||||
```
|
||||
- `Core::Event<Scene*>&` - 活动场景切换事件对象引用。
|
||||
|
||||
## 相关文档
|
||||
|
||||
- [返回类总览](SceneManager.md)
|
||||
- [返回模块目录](../Scene.md)
|
||||
- [返回类型总览](SceneManager.md)
|
||||
- [SetActiveScene](SetActiveScene.md)
|
||||
- [Event](../../Core/Event/Event.md)
|
||||
|
||||
@@ -1,30 +1,23 @@
|
||||
# SceneManager::OnSceneLoaded
|
||||
|
||||
公开方法，详见头文件声明。
|
||||
访问场景加载事件。
|
||||
|
||||
```cpp
|
||||
Core::Event<Scene*>& OnSceneLoaded();
|
||||
```
|
||||
|
||||
该方法声明于 `XCEngine/Scene/SceneManager.h`，当前页面用于固定 `SceneManager` 类目录下的方法级 canonical 路径。
|
||||
## 行为说明
|
||||
|
||||
**参数：** 无。
|
||||
当前头文件内联实现直接返回 `m_onSceneLoaded` 的引用。
|
||||
|
||||
**返回：** `Core::Event<Scene*>&` - 返回值语义详见头文件声明。
|
||||
这个事件在 [CreateScene](CreateScene.md) 和 [LoadScene](LoadScene.md) 中都会触发。
|
||||
|
||||
**示例：**
|
||||
## 返回值
|
||||
|
||||
```cpp
|
||||
#include <XCEngine/Scene/SceneManager.h>
|
||||
|
||||
void Example() {
|
||||
XCEngine::Components::SceneManager object;
|
||||
// 根据上下文补齐参数后调用 SceneManager::OnSceneLoaded(...)。
|
||||
(void)object;
|
||||
}
|
||||
```
|
||||
- `Core::Event<Scene*>&` - 场景加载事件对象引用。
|
||||
|
||||
## 相关文档
|
||||
|
||||
- [返回类总览](SceneManager.md)
|
||||
- [返回模块目录](../Scene.md)
|
||||
- [返回类型总览](SceneManager.md)
|
||||
- [CreateScene](CreateScene.md)
|
||||
- [LoadScene](LoadScene.md)
|
||||
|
||||
@@ -1,30 +1,22 @@
|
||||
# SceneManager::OnSceneUnloaded
|
||||
|
||||
公开方法，详见头文件声明。
|
||||
访问场景卸载事件。
|
||||
|
||||
```cpp
|
||||
Core::Event<Scene*>& OnSceneUnloaded();
|
||||
```
|
||||
|
||||
该方法声明于 `XCEngine/Scene/SceneManager.h`，当前页面用于固定 `SceneManager` 类目录下的方法级 canonical 路径。
|
||||
## 行为说明
|
||||
|
||||
**参数：** 无。
|
||||
当前头文件内联实现直接返回 `m_onSceneUnloaded` 的引用。
|
||||
|
||||
**返回：** `Core::Event<Scene*>&` - 返回值语义详见头文件声明。
|
||||
该事件在 [UnloadScene](UnloadScene.md) 找到并真正移除场景时触发。
|
||||
|
||||
**示例：**
|
||||
## 返回值
|
||||
|
||||
```cpp
|
||||
#include <XCEngine/Scene/SceneManager.h>
|
||||
|
||||
void Example() {
|
||||
XCEngine::Components::SceneManager object;
|
||||
// 根据上下文补齐参数后调用 SceneManager::OnSceneUnloaded(...)。
|
||||
(void)object;
|
||||
}
|
||||
```
|
||||
- `Core::Event<Scene*>&` - 场景卸载事件对象引用。
|
||||
|
||||
## 相关文档
|
||||
|
||||
- [返回类总览](SceneManager.md)
|
||||
- [返回模块目录](../Scene.md)
|
||||
- [返回类型总览](SceneManager.md)
|
||||
- [UnloadScene](UnloadScene.md)
|
||||
|
||||
@@ -6,36 +6,57 @@
|
||||
|
||||
**头文件**: `XCEngine/Scene/SceneManager.h`
|
||||
|
||||
**描述**: 定义 `XCEngine/Scene` 子目录中的 `SceneManager` public API。
|
||||
**描述**: 维护已加载场景集合并提供活动场景入口的全局场景管理器。
|
||||
|
||||
## 概述
|
||||
|
||||
`SceneManager.h` 是 `XCEngine/Scene` 子目录 下的 public header，当前页面作为平行目录中的 canonical 总览，用于汇总该头文件暴露的主要声明。
|
||||
`SceneManager` 负责的是“场景注册表”和“当前活动场景指针”，而不是完整的场景调度框架。它内部维护：
|
||||
|
||||
## 声明概览
|
||||
- `m_scenes`，按字符串 key 保存场景唯一所有权。
|
||||
- `m_activeScene`，保存当前活动场景裸指针。
|
||||
- 三个场景级事件对象。
|
||||
|
||||
| 声明 | 类型 | 说明 |
|
||||
|------|------|------|
|
||||
| `SceneManager` | `class` | 头文件中的公开声明。 |
|
||||
这种设计对应很多商业引擎里的“全局场景入口”思路：上层系统通过一个统一位置拿到活动场景或切换已加载场景，而不是自己持有所有场景集合。
|
||||
|
||||
## 公共方法
|
||||
## 所有权与 key 规则
|
||||
|
||||
| 方法 | 描述 |
|
||||
- [CreateScene](CreateScene.md) 创建的场景以传入 `name` 作为 map key。
|
||||
- [LoadScene](LoadScene.md) 加载的场景以“文件名 stem”作为 map key，而不是文件内部保存的 `scene=` 名称。
|
||||
- `GetScene()`、`UnloadScene(const std::string&)` 和 `SetActiveScene(const std::string&)` 都使用这个内部 key。
|
||||
- 如果场景对象后续调用 `Scene::SetName()` 改名，当前 key 不会自动重建。
|
||||
|
||||
## 当前实现边界
|
||||
|
||||
- 当前没有锁；不适合并发加载或并发卸载。
|
||||
- [LoadSceneAsync](LoadSceneAsync.md) 目前不是异步，只是同步调用再执行回调。
|
||||
- [LoadSceneAsync](LoadSceneAsync.md) 的回调查找使用原始 `filePath` 做 key，常见情况下会得到 `nullptr`。
|
||||
- `SceneManager` 的活动场景指针，与 `Scene::IsActive()` / `SetActive()` 当前没有自动同步关系。
|
||||
- [SetActiveScene](SetActiveScene.md) 的指针重载不会校验传入场景是否真的来自 `m_scenes`。
|
||||
- 如果使用相同 key 重复创建或加载场景，旧场景会被新场景替换；这可能让先前缓存的裸指针失效。
|
||||
|
||||
## 线程语义
|
||||
|
||||
- 当前没有内部同步；应把它当作主线程系统使用。
|
||||
|
||||
## 公开方法
|
||||
|
||||
| 方法 | 说明 |
|
||||
|------|------|
|
||||
| [Get](Get.md) | 获取相关状态或对象。 |
|
||||
| [CreateScene](CreateScene.md) | 创建新对象或资源。 |
|
||||
| [LoadScene](LoadScene.md) | 加载资源或数据。 |
|
||||
| [LoadSceneAsync](LoadSceneAsync.md) | 加载资源或数据。 |
|
||||
| [UnloadScene](UnloadScene.md) | 卸载资源或释放缓存。 |
|
||||
| [SetActiveScene](SetActiveScene.md) | 设置相关状态或配置。 |
|
||||
| [GetActiveScene](GetActiveScene.md) | 获取相关状态或对象。 |
|
||||
| [GetScene](GetScene.md) | 获取相关状态或对象。 |
|
||||
| [GetAllScenes](GetAllScenes.md) | 获取相关状态或对象。 |
|
||||
| [OnSceneLoaded](OnSceneLoaded.md) | 公开方法，详见头文件声明。 |
|
||||
| [OnSceneUnloaded](OnSceneUnloaded.md) | 公开方法，详见头文件声明。 |
|
||||
| [OnActiveSceneChanged](OnActiveSceneChanged.md) | 公开方法，详见头文件声明。 |
|
||||
| [Get](Get.md) | 获取单例。 |
|
||||
| [CreateScene](CreateScene.md) | 创建并登记场景。 |
|
||||
| [LoadScene](LoadScene.md) | 从文件加载并登记场景。 |
|
||||
| [LoadSceneAsync](LoadSceneAsync.md) | 当前的同步包装“异步”加载接口。 |
|
||||
| [UnloadScene](UnloadScene.md) | 卸载场景。 |
|
||||
| [SetActiveScene](SetActiveScene.md) | 设置活动场景。 |
|
||||
| [GetActiveScene](GetActiveScene.md) | 获取活动场景。 |
|
||||
| [GetScene](GetScene.md) | 按 key 获取场景。 |
|
||||
| [GetAllScenes](GetAllScenes.md) | 获取全部已登记场景。 |
|
||||
| [OnSceneLoaded](OnSceneLoaded.md) | 访问场景加载事件。 |
|
||||
| [OnSceneUnloaded](OnSceneUnloaded.md) | 访问场景卸载事件。 |
|
||||
| [OnActiveSceneChanged](OnActiveSceneChanged.md) | 访问活动场景切换事件。 |
|
||||
|
||||
## 相关文档
|
||||
|
||||
- [当前目录](../Scene.md) - 返回 `Scene` 平行目录
|
||||
- [API 总索引](../../../main.md) - 返回顶层索引
|
||||
- [当前模块](../Scene.md)
|
||||
- [Scene](../Scene/Scene.md)
|
||||
- [Scene Lifecycle And Serialization](../../../_guides/Scene/Scene-Lifecycle-And-Serialization.md)
|
||||
|
||||
@@ -1,44 +1,36 @@
|
||||
# SceneManager::SetActiveScene
|
||||
|
||||
设置相关状态或配置。
|
||||
|
||||
该方法在 `XCEngine/Scene/SceneManager.h` 中提供了 2 个重载，当前页面统一汇总这些公开声明。
|
||||
|
||||
## 重载 1: 声明
|
||||
设置活动场景。
|
||||
|
||||
```cpp
|
||||
void SetActiveScene(Scene* scene);
|
||||
```
|
||||
|
||||
**参数：**
|
||||
- `scene` - 参数语义详见头文件声明。
|
||||
|
||||
**返回：** `void` - 无返回值。
|
||||
|
||||
## 重载 2: 声明
|
||||
|
||||
```cpp
|
||||
void SetActiveScene(const std::string& sceneName);
|
||||
```
|
||||
|
||||
**参数：**
|
||||
- `sceneName` - 参数语义详见头文件声明。
|
||||
## 行为说明
|
||||
|
||||
**返回：** `void` - 无返回值。
|
||||
当前有两个重载：
|
||||
|
||||
**示例：**
|
||||
- 指针重载会在 `m_activeScene != scene` 时直接写入 `m_activeScene = scene`，然后触发 [OnActiveSceneChanged](OnActiveSceneChanged.md)。
|
||||
- 字符串重载会先在 `m_scenes` 中查找 key，找到后再调用指针重载。
|
||||
|
||||
```cpp
|
||||
#include <XCEngine/Scene/SceneManager.h>
|
||||
## 参数
|
||||
|
||||
void Example() {
|
||||
XCEngine::Components::SceneManager object;
|
||||
// 根据上下文补齐参数后调用 SceneManager::SetActiveScene(...)。
|
||||
(void)object;
|
||||
}
|
||||
```
|
||||
- `scene` - 目标活动场景指针。
|
||||
- `sceneName` - 目标场景 key。
|
||||
|
||||
## 返回值
|
||||
|
||||
- 无。
|
||||
|
||||
## 当前实现限制
|
||||
|
||||
- 指针重载不会校验 `scene` 是否真的来自 `SceneManager` 当前持有的场景集合。
|
||||
- 当前不会同步 `Scene::SetActive()`。
|
||||
- 如果传入的指针就是当前活动场景，不会触发事件。
|
||||
- 传入 `nullptr` 时，如果当前活动场景非空，会把活动场景清空并触发切换事件。
|
||||
|
||||
## 相关文档
|
||||
|
||||
- [返回类总览](SceneManager.md)
|
||||
- [返回模块目录](../Scene.md)
|
||||
- [返回类型总览](SceneManager.md)
|
||||
- [GetActiveScene](GetActiveScene.md)
|
||||
|
||||
@@ -1,44 +1,41 @@
|
||||
# SceneManager::UnloadScene
|
||||
|
||||
卸载资源或释放缓存。
|
||||
|
||||
该方法在 `XCEngine/Scene/SceneManager.h` 中提供了 2 个重载，当前页面统一汇总这些公开声明。
|
||||
|
||||
## 重载 1: 声明
|
||||
卸载一个已登记场景。
|
||||
|
||||
```cpp
|
||||
void UnloadScene(Scene* scene);
|
||||
```
|
||||
|
||||
**参数：**
|
||||
- `scene` - 参数语义详见头文件声明。
|
||||
|
||||
**返回：** `void` - 无返回值。
|
||||
|
||||
## 重载 2: 声明
|
||||
|
||||
```cpp
|
||||
void UnloadScene(const std::string& sceneName);
|
||||
```
|
||||
|
||||
**参数：**
|
||||
- `sceneName` - 参数语义详见头文件声明。
|
||||
## 行为说明
|
||||
|
||||
**返回：** `void` - 无返回值。
|
||||
当前有两个重载：
|
||||
|
||||
**示例：**
|
||||
- 指针重载：
|
||||
1. `scene == nullptr` 时直接返回。
|
||||
2. 如果它正好是 `m_activeScene`，先把活动场景清空。
|
||||
3. 在 `m_scenes` 里线性查找匹配指针。
|
||||
4. 找到后触发 [OnSceneUnloaded](OnSceneUnloaded.md)，然后擦除。
|
||||
5. 如果活动场景为空且仍有剩余场景，选择 `m_scenes.begin()` 作为新的活动场景，并触发 [OnActiveSceneChanged](OnActiveSceneChanged.md)。
|
||||
- 字符串重载：先按 key 查找，再转到指针重载。
|
||||
|
||||
```cpp
|
||||
#include <XCEngine/Scene/SceneManager.h>
|
||||
## 参数
|
||||
|
||||
void Example() {
|
||||
XCEngine::Components::SceneManager object;
|
||||
// 根据上下文补齐参数后调用 SceneManager::UnloadScene(...)。
|
||||
(void)object;
|
||||
}
|
||||
```
|
||||
- `scene` - 待卸载场景指针。
|
||||
- `sceneName` - 待卸载场景 key。
|
||||
|
||||
## 返回值
|
||||
|
||||
- 无。
|
||||
|
||||
## 当前实现限制
|
||||
|
||||
- 后备活动场景来自 `unordered_map` 首元素，选择顺序不稳定。
|
||||
- 如果卸载的是最后一个活动场景，当前不会额外发出“活动场景变为 `nullptr`”的切换事件。
|
||||
- 指针重载内部需要线性扫描 map 找到匹配场景。
|
||||
|
||||
## 相关文档
|
||||
|
||||
- [返回类总览](SceneManager.md)
|
||||
- [返回模块目录](../Scene.md)
|
||||
- [返回类型总览](SceneManager.md)
|
||||
- [OnSceneUnloaded](OnSceneUnloaded.md)
|
||||
- [OnActiveSceneChanged](OnActiveSceneChanged.md)
|
||||
|
||||
Reference in New Issue
Block a user