3.6 KiB
3.6 KiB
LayerStack
命名空间: XCEngine::Core
类型: class
头文件: XCEngine/Core/LayerStack.h
描述: 一个按“普通层 + overlay”分段组织的 Layer 容器，负责遍历和基础生命周期分发。
角色概述
LayerStack 负责管理多个 Layer 实例的顺序关系。它把容器分成两段：
- 普通 layers
- overlays
这是一种常见的应用壳层设计，适合把“主功能层”和“悬浮 UI / 调试覆盖层”分开组织。
当前实现行为
1. 所有权由 std::unique_ptr<Layer> 表达
LayerStack 内部直接持有：
std::vector<std::unique_ptr<Layer>> m_layers
因此：
- stack 拥有 layer 生命周期
pushLayer()/pushOverlay()都会转移 unique ownershippopLayer()/popOverlay()删除元素时会触发对象析构
2. 普通层和 overlay 的分界靠 m_layerInsertIndex
pushLayer() 会把新层插入 m_layers.begin() + m_layerInsertIndex，然后递增索引；pushOverlay() 则直接追加到尾部。
这意味着当前排序规则是：
- 普通层保持在前半段
- overlay 永远位于后半段
3. push* 不会自动调用 onAttach()
这是一个非常重要的当前行为。很多引擎框架会在 push 时立刻 attach，但当前实现不会：
pushLayer()只做插入pushOverlay()只做插入
真正的 attach 分发只发生在显式调用 onAttach 时。
4. pop* 会调用 onDetach()
相对地，popLayer() 和 popOverlay() 在删除元素前都会先调用对应 layer 的 onDetach()。
5. 遍历顺序是正向遍历
以下分发方法当前都按 m_layers 的正向顺序调用：
onUpdate()onEvent()onImGuiRender()onAttach()onDetach()
这尤其意味着 onEvent() 不是“从 top-most overlay 逆向往下传”的模式，而是从前到后正向调用。对有事件吞噬需求的系统来说，这一点必须明确。
迭代器暴露
LayerStack 同时暴露了：
begin()/end()rbegin()/rend()cbegin()/cend()crbegin()/crend()
这让外部可以按需要自定义遍历顺序，但也说明它没有封装成强约束的调度器。
当前代码库中的使用情况
在当前取证范围内，没有看到它在 engine/src 里形成广泛调用链。因此这更像基础应用框架能力，而不是当前引擎主运行时的核心主线。
线程语义
- 当前实现没有加锁。
- 所有修改和遍历都应按单线程外部驱动理解。
当前实现限制
pushLayer()/pushOverlay()不会自动onAttach()。onDetach()在pop*时会调用，但析构函数本身是默认实现，不会自动遍历 detach 剩余层。onEvent()采用正向遍历，不是常见的逆向 overlay 优先分发。- 没有看到直接测试覆盖。
相关方法
- Constructor
- Destructor
- pushLayer
- pushOverlay
- popLayer
- popOverlay
- onUpdate
- onEvent
- onImGuiRender
- onAttach
- onDetach
- begin
- end
- rbegin
- rend
- cbegin
- cend
- crbegin
- crend