# InputManager

**命名空间**: `XCEngine::Input`

**类型**: `class (singleton)`

**头文件**: `XCEngine/Input/InputManager.h`

**描述**: 保存当前输入状态、提供轮询查询接口，并同步广播输入事件。

## 概述

`InputManager` 是 XCEngine 当前输入系统的核心入口。平台层通过 `ProcessKeyDown`、`ProcessMouseMove` 等方法把原始输入送进来；游戏代码、编辑器和测试代码则通过 `IsKeyDown`、`GetAxis`、`OnKeyEvent` 等 API 查询或订阅这些状态。

它同时承担两种角色：

- 轮询中心：保存“当前是否按下”“本帧是否刚按下”“本帧鼠标位移”等状态。
- 事件中心：把输入变化同步广播给订阅者。

## 生命周期

- [Get](Get.md) 返回进程级单例。
- [Initialize](Initialize.md) 分配内部状态数组、保存窗口句柄并注册默认轴/按钮。
- [Shutdown](Shutdown.md) 清空状态和映射，但当前不会清空事件监听器。
- [Update](Update.md) 用于推进帧边界并清理瞬时状态。

## 默认映射

当前 `Initialize` 会注册以下默认逻辑项：

- 轴：`Horizontal` (`D` / `A`)、`Vertical` (`W` / `S`)
- 轴：`Mouse X`、`Mouse Y`，但两者当前都绑定为 `KeyCode::None`，因此 `GetAxis` 结果始终为 `0`
- 按钮：`Jump` (`Space`)、`Fire1` (`LeftCtrl`)、`Fire2` (`LeftAlt`)、`Fire3` (`LeftShift`)

## 线程语义

- 当前实现没有锁，也不是为多线程输入注入设计的。
- `Process*`、`Update`、注册映射和查询最好都在主线程或同一逻辑线程完成。
- 事件回调同步执行在调用 `Process*` 的线程上。

## 当前实现限制

- `platformWindowHandle` 会被保存，但 `InputManager` 当前并不直接使用它。
- `KeyCode` 数值存在重复项，而 `InputManager` 用原始枚举值索引固定数组，因此部分按键状态会别名冲突。
- `GetAxisRaw` 当前按“按下这一帧”计算，而不是按“持续按住”计算。
- `GetButtonUp` 对未注册按钮返回 `true`。
- `ClearAxes` 会同时清空 `m_axes` 和 `m_buttons`。
- 触摸接口已暴露，但当前实现没有任何公开路径去填充 `m_touches`。

## 公开方法

| 方法 | 说明 |
|------|------|
| [Get](Get.md) | 获取全局 `InputManager` 实例。 |
| [Initialize](Initialize.md) | 初始化输入状态和默认映射。 |
| [Shutdown](Shutdown.md) | 清空输入状态与映射。 |
| [Update](Update.md) | 推进帧边界并清理瞬时状态。 |
| [IsKeyDown](IsKeyDown.md) | 查询键是否处于按下状态。 |
| [IsKeyUp](IsKeyUp.md) | 查询键是否处于抬起状态。 |
| [IsKeyPressed](IsKeyPressed.md) | 查询键是否在本帧刚被按下。 |
| [GetMousePosition](GetMousePosition.md) | 读取当前鼠标位置。 |
| [GetMouseDelta](GetMouseDelta.md) | 读取本帧鼠标位移。 |
| [GetMouseScrollDelta](GetMouseScrollDelta.md) | 读取本帧滚轮增量。 |
| [IsMouseButtonDown](IsMouseButtonDown.md) | 查询鼠标按键是否按下。 |
| [IsMouseButtonUp](IsMouseButtonUp.md) | 查询鼠标按键是否抬起。 |
| [IsMouseButtonClicked](IsMouseButtonClicked.md) | 查询鼠标按键是否在本帧刚被按下。 |
| [GetTouchCount](GetTouchCount.md) | 读取触点数量。 |
| [GetTouch](GetTouch.md) | 读取指定触点状态。 |
| [GetAxis](GetAxis.md) | 读取具名逻辑轴。 |
| [GetAxisRaw](GetAxisRaw.md) | 读取具名逻辑轴的当前原始值。 |
| [GetButton](GetButton.md) | 查询具名按钮当前是否按下。 |
| [GetButtonDown](GetButtonDown.md) | 查询具名按钮是否在本帧刚按下。 |
| [GetButtonUp](GetButtonUp.md) | 查询具名按钮是否处于抬起状态。 |
| [RegisterAxis](RegisterAxis.md) | 注册或覆盖一个具名轴。 |
| [RegisterButton](RegisterButton.md) | 注册或覆盖一个具名按钮。 |
| [ClearAxes](ClearAxes.md) | 清空轴和按钮映射。 |
| [OnKeyEvent](OnKeyEvent.md) | 获取键盘事件通道。 |
| [OnMouseButton](OnMouseButton.md) | 获取鼠标按键事件通道。 |
| [OnMouseMove](OnMouseMove.md) | 获取鼠标移动事件通道。 |
| [OnMouseWheel](OnMouseWheel.md) | 获取鼠标滚轮事件通道。 |
| [OnTextInput](OnTextInput.md) | 获取文本输入事件通道。 |
| [ProcessKeyDown](ProcessKeyDown.md) | 注入按键按下事件。 |
| [ProcessKeyUp](ProcessKeyUp.md) | 注入按键抬起事件。 |
| [ProcessMouseMove](ProcessMouseMove.md) | 注入鼠标移动事件。 |
| [ProcessMouseButton](ProcessMouseButton.md) | 注入鼠标按键事件。 |
| [ProcessMouseWheel](ProcessMouseWheel.md) | 注入鼠标滚轮事件。 |
| [ProcessTextInput](ProcessTextInput.md) | 注入文本输入事件。 |

## 相关文档

- [当前模块](../Input.md)
- [InputAxis](../InputAxis/InputAxis.md)
- [InputEvent](../InputEvent/InputEvent.md)
- [Input Flow And Frame Semantics](../../../_guides/Input/Input-Flow-and-Frame-Semantics.md)