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

docs: rebuild Input API content

Browse Source
This commit is contained in:
ssdfasd
2026-03-26 17:39:53 +08:00
parent ec4edb2689
commit ce2eee32e3
54 changed files with 1108 additions and 941 deletions
Download Patch File Download Diff File Expand all files Collapse all files

47
docs/api/XCEngine/Input/Input.md
View File

@@ -4,19 +4,50 @@
**类型**: `module` **类型**: `module`
**描述**: 输入状态查询、输入事件与平台接入接口。 **描述**: 提供输入状态查询、逻辑轴与按钮映射、同步事件分发以及平台输入桥接接口。
## 概览 ## 概述
该目录与 `XCEngine/Input` 对应的 public headers 保持平行，用于承载唯一的 canonical API 文档入口。 `XCEngine::Input` 解决的是“如何把平台消息变成引擎可查询输入状态”这个问题。当前模块的核心由两层组成：
- `InputManager` 负责保存当前帧输入状态、提供轮询查询接口，并同步分发输入事件。
- `InputModule` 负责定义平台桥接接口，把操作系统窗口消息翻译成 `InputManager::Process*` 调用。
当前版本的成熟度是分层的：
- 键盘与鼠标的基础轮询和事件分发已经可用，并且有单元测试覆盖。
- Windows 路径已经有实际桥接实现 `WindowsInputModule`。
- 触摸与摇杆相关 API 仍然偏预留位，当前 `InputManager` 自身并不会产生这些输入。
## 设计要点
- 同时保留轮询接口和事件接口，方便游戏逻辑与 UI 系统按各自习惯接入。
- 逻辑轴和逻辑按钮采用名字映射，风格上接近 Unity 旧版 Input Manager，而不是设备级输入系统。
- 平台桥接与输入状态解耦，`InputModule` 可以替换，而游戏代码继续依赖 `InputManager`。
- 当前实现是轻量级同步模型，不是线程安全的跨平台输入框架。
## 当前实现限制
- `GetAxisRaw` 当前按“本帧按下边沿”计算，而不是按“持续按住”计算，这一点和很多引擎的 `GetAxisRaw` 直觉不同。
- `ClearAxes` 会同时清空轴和按钮映射，名字比实际行为更窄。
- `InputTypes::KeyCode` 的底层数值当前存在重复项，而 `InputManager` 又直接把这些值当作数组下标。
- `InputManager` 暴露了触摸接口，但当前代码路径没有填充触摸状态。
## 头文件 ## 头文件
- [InputAxis](InputAxis/InputAxis.md) - `InputAxis.h` - [InputAxis](InputAxis/InputAxis.md) - `InputAxis.h`，逻辑轴配置对象。
- [InputEvent](InputEvent/InputEvent.md) - `InputEvent.h` - [InputEvent](InputEvent/InputEvent.md) - `InputEvent.h`，输入事件结构体定义。
- [InputManager](InputManager/InputManager.md) - `InputManager.h` - [InputManager](InputManager/InputManager.md) - `InputManager.h`，全局输入状态与事件中心。
- [InputModule](InputModule/InputModule.md) - `InputModule.h` - [InputModule](InputModule/InputModule.md) - `InputModule.h`，平台输入桥接接口。
- [InputTypes](InputTypes/InputTypes.md) - `InputTypes.h` - [InputTypes](InputTypes/InputTypes.md) - `InputTypes.h`，键盘、鼠标和摇杆的基础枚举。
## 相关指南
- [Input Flow And Frame Semantics](../../_guides/Input/Input-Flow-and-Frame-Semantics.md) - 解释事件、轮询、帧边界和平台桥接如何配合工作。
## 相关实现
- [WindowsInputModule](../Platform/Windows/WindowsInputModule/WindowsInputModule.md) - Windows 平台当前的具体输入桥接实现。
## 相关文档 ## 相关文档

54
docs/api/XCEngine/Input/InputAxis/Constructor.md
View File

@@ -1,43 +1,39 @@
# InputAxis::InputAxis() # InputAxis::Constructor
构造对象。 构造一个逻辑轴配置对象。
该方法在 `XCEngine/Input/InputAxis.h` 中提供了 2 个重载，当前页面统一汇总这些公开声明。
## 重载 1: 声明
```cpp ```cpp
InputAxis() = default; InputAxis() = default;
InputAxis(const Containers::String& name, KeyCode positive, KeyCode negative = KeyCode::None);
``` ```
**参数：** 无。 ## 行为说明
**返回：** `void` - 无返回值。 默认构造会创建一个空轴：
## 重载 2: 声明 - 名称为空
- 正负方向键都为 `KeyCode::None`
- 内部 `m_value` 为 `0.0f`
具名构造会同时设置轴名和正负方向按键。当前 `InputManager` 注册逻辑轴时，通常使用这个构造形式。
## 参数
- `name` - 逻辑轴名称。
- `positive` - 正方向按键。
- `negative` - 负方向按键；默认是 `KeyCode::None`。
## 返回值
- 无。
## 示例
```cpp ```cpp
InputAxis(const Containers::String& name, KeyCode positive, KeyCode negative = KeyCode::None) : m_name(name), m_positiveKey(positive), m_negativeKey(negative); XCEngine::Input::InputAxis axis("Horizontal", XCEngine::Input::KeyCode::D, XCEngine::Input::KeyCode::A);
```
**参数：**
- `name` - 参数语义详见头文件声明。
- `positive` - 参数语义详见头文件声明。
- `negative` - 参数语义详见头文件声明。
**返回：** `void` - 无返回值。
**示例：**
```cpp
#include <XCEngine/Input/InputAxis.h>
void Example() {
XCEngine::Input::InputAxis object;
}
``` ```
## 相关文档 ## 相关文档
- [返回类总览](InputAxis.md) - [返回类型总览](InputAxis.md)
- [返回模块目录](../Input.md) - [SetKeys](SetKeys.md)

24
docs/api/XCEngine/Input/InputAxis/GetName.md
View File

@@ -1,30 +1,26 @@
# InputAxis::GetName # InputAxis::GetName
获取相关状态或对象。 读取轴名。
```cpp ```cpp
const Containers::String& GetName() const; const Containers::String& GetName() const;
``` ```
该方法声明于 `XCEngine/Input/InputAxis.h`，当前页面用于固定 `InputAxis` 类目录下的方法级 canonical 路径。 ## 行为说明
**参数：** 无。 返回内部保存的名称引用，不做复制、不做标准化，也不会检查唯一性。`InputManager::RegisterAxis` 会用这个名称作为映射键。
**返回：** `const Containers::String&` - 返回值语义详见头文件声明。 ## 返回值
**示例：** - `const Containers::String&` - 当前轴名。
## 示例
```cpp ```cpp
#include <XCEngine/Input/InputAxis.h> XCEngine::Input::InputAxis axis("Vertical", XCEngine::Input::KeyCode::W, XCEngine::Input::KeyCode::S);
auto& name = axis.GetName();
void Example() {
XCEngine::Input::InputAxis object;
// 根据上下文补齐参数后调用 InputAxis::GetName(...)。
(void)object;
}
``` ```
## 相关文档 ## 相关文档
- [返回类总览](InputAxis.md) - [返回类型总览](InputAxis.md)
- [返回模块目录](../Input.md)

24
docs/api/XCEngine/Input/InputAxis/GetNegativeKey.md
View File

@@ -1,30 +1,26 @@
# InputAxis::GetNegativeKey # InputAxis::GetNegativeKey
获取相关状态或对象。 读取轴的负方向按键。
```cpp ```cpp
KeyCode GetNegativeKey() const; KeyCode GetNegativeKey() const;
``` ```
该方法声明于 `XCEngine/Input/InputAxis.h`，当前页面用于固定 `InputAxis` 类目录下的方法级 canonical 路径。 ## 行为说明
**参数：** 无。 当前返回内部保存的 `m_negativeKey`。如果返回 `KeyCode::None`，表示该轴当前没有配置负方向键。
**返回：** `KeyCode` - 返回值语义详见头文件声明。 ## 返回值
**示例：** - `KeyCode` - 负方向按键。
## 示例
```cpp ```cpp
#include <XCEngine/Input/InputAxis.h> XCEngine::Input::KeyCode negative = axis.GetNegativeKey();
void Example() {
XCEngine::Input::InputAxis object;
// 根据上下文补齐参数后调用 InputAxis::GetNegativeKey(...)。
(void)object;
}
``` ```
## 相关文档 ## 相关文档
- [返回类总览](InputAxis.md) - [返回类型总览](InputAxis.md)
- [返回模块目录](../Input.md) - [GetPositiveKey](GetPositiveKey.md)

24
docs/api/XCEngine/Input/InputAxis/GetPositiveKey.md
View File

@@ -1,30 +1,26 @@
# InputAxis::GetPositiveKey # InputAxis::GetPositiveKey
获取相关状态或对象。 读取轴的正方向按键。
```cpp ```cpp
KeyCode GetPositiveKey() const; KeyCode GetPositiveKey() const;
``` ```
该方法声明于 `XCEngine/Input/InputAxis.h`，当前页面用于固定 `InputAxis` 类目录下的方法级 canonical 路径。 ## 行为说明
**参数：** 无。 当前返回内部保存的 `m_positiveKey`。如果返回 `KeyCode::None`，表示该轴当前没有配置正方向键。
**返回：** `KeyCode` - 返回值语义详见头文件声明。 ## 返回值
**示例：** - `KeyCode` - 正方向按键。
## 示例
```cpp ```cpp
#include <XCEngine/Input/InputAxis.h> XCEngine::Input::KeyCode positive = axis.GetPositiveKey();
void Example() {
XCEngine::Input::InputAxis object;
// 根据上下文补齐参数后调用 InputAxis::GetPositiveKey(...)。
(void)object;
}
``` ```
## 相关文档 ## 相关文档
- [返回类总览](InputAxis.md) - [返回类型总览](InputAxis.md)
- [返回模块目录](../Input.md) - [GetNegativeKey](GetNegativeKey.md)

29
docs/api/XCEngine/Input/InputAxis/GetValue.md
View File

@@ -1,30 +1,31 @@
# InputAxis::GetValue # InputAxis::GetValue
获取相关状态或对象。 读取 `InputAxis` 对象内部保存的数值。
```cpp ```cpp
float GetValue() const; float GetValue() const;
``` ```
该方法声明于 `XCEngine/Input/InputAxis.h`，当前页面用于固定 `InputAxis` 类目录下的方法级 canonical 路径。 ## 行为说明
**参数：** 无。 这个值只是 `InputAxis` 对象自己的成员 `m_value`。当前 `InputManager::GetAxis` 和 `GetAxisRaw` 不会读取它，而是根据按键状态重新计算轴值。
**返回：** `float` - 返回值语义详见头文件声明。 因此，它更像是一个通用配置/缓存字段，而不是 `InputManager` 的真实运行时输出。
**示例：** ## 返回值
- `float` - 当前对象内部保存的数值。
## 示例
```cpp ```cpp
#include <XCEngine/Input/InputAxis.h> XCEngine::Input::InputAxis axis;
axis.SetValue(0.5f);
void Example() { float value = axis.GetValue();
XCEngine::Input::InputAxis object;
// 根据上下文补齐参数后调用 InputAxis::GetValue(...)。
(void)object;
}
``` ```
## 相关文档 ## 相关文档
- [返回类总览](InputAxis.md) - [返回类型总览](InputAxis.md)
- [返回模块目录](../Input.md) - [SetValue](SetValue.md)
- [InputManager::GetAxis](../InputManager/GetAxis.md)

46
docs/api/XCEngine/Input/InputAxis/InputAxis.md
View File

@@ -6,31 +6,43 @@
**头文件**: `XCEngine/Input/InputAxis.h` **头文件**: `XCEngine/Input/InputAxis.h`
**描述**: 定义 `XCEngine/Input` 子目录中的 `InputAxis` public API。 **描述**: 描述一个具名逻辑轴及其正负方向按键映射。
## 概述 ## 概述
`InputAxis.h` 是 `XCEngine/Input` 子目录 下的 public header，当前页面作为平行目录中的 canonical 总览，用于汇总该头文件暴露的主要声明。 `InputAxis` 是 `InputManager` 的配置对象，而不是完整的运行时输入通道。它保存三类信息：
## 声明概览 - 轴名
- 正方向按键
- 负方向按键
| 声明 | 类型 | 说明 | 此外它还有一个独立的 `m_value` 字段，但要特别注意：当前 `InputManager::GetAxis` 和 `GetAxisRaw` 都不会读取这个值，而是每次根据按键状态重新计算结果。
|------|------|------|
| `InputAxis` | `class` | 头文件中的公开声明。 |
## 公共方法 ## 当前实现中的角色
| 方法 | 描述 | - 在 `InputManager::Initialize` 时，用它注册默认的 `Horizontal`、`Vertical`、`Mouse X` 和 `Mouse Y` 逻辑轴。
- 在运行时，可通过 [RegisterAxis](../InputManager/RegisterAxis.md) 注册自定义具名轴。
- 当前只支持“两键一轴”模型，不支持平滑曲线、死区、灵敏度或设备组合。
## 生命周期
- [Constructor](Constructor.md) 支持默认构造和具名按键构造。
- `InputAxis` 是值类型，通常按值传给 `InputManager`。
## 公开方法
| 方法 | 说明 |
|------|------| |------|------|
| [InputAxis()](Constructor.md) | 构造对象。 | | [Constructor](Constructor.md) | 构造一个轴配置对象。 |
| [GetName](GetName.md) | 获取相关状态或对象。 | | [GetName](GetName.md) | 读取轴名。 |
| [GetPositiveKey](GetPositiveKey.md) | 获取相关状态或对象。 | | [GetPositiveKey](GetPositiveKey.md) | 读取正方向按键。 |
| [GetNegativeKey](GetNegativeKey.md) | 获取相关状态或对象。 | | [GetNegativeKey](GetNegativeKey.md) | 读取负方向按键。 |
| [SetKeys](SetKeys.md) | 设置相关状态或配置。 | | [SetKeys](SetKeys.md) | 修改正负方向按键。 |
| [GetValue](GetValue.md) | 获取相关状态或对象。 | | [GetValue](GetValue.md) | 读取对象自身保存的值。 |
| [SetValue](SetValue.md) | 设置相关状态或配置。 | | [SetValue](SetValue.md) | 写入对象自身保存的值。 |
## 相关文档 ## 相关文档
- [当前目录](../Input.md) - 返回 `Input` 平行目录 - [当前模块](../Input.md)
- [API 总索引](../../../main.md) - 返回顶层索引 - [InputManager](../InputManager/InputManager.md)
- [Input Flow And Frame Semantics](../../../_guides/Input/Input-Flow-and-Frame-Semantics.md)

31
docs/api/XCEngine/Input/InputAxis/SetKeys.md
View File

@@ -1,32 +1,31 @@
# InputAxis::SetKeys # InputAxis::SetKeys
设置相关状态或配置。 修改轴的正负方向按键。
```cpp ```cpp
void SetKeys(KeyCode positive, KeyCode negative); void SetKeys(KeyCode positive, KeyCode negative);
``` ```
该方法声明于 `XCEngine/Input/InputAxis.h`，当前页面用于固定 `InputAxis` 类目录下的方法级 canonical 路径。 ## 行为说明
**参数：** 当前实现仅更新内部两个键值字段，不做合法性检查，也不会通知 `InputManager`。如果这个对象已经按值注册进 `InputManager`，后续再修改原对象不会影响 `InputManager` 内部保存的副本。
- `positive` - 参数语义详见头文件声明。
- `negative` - 参数语义详见头文件声明。
**返回：** `void` - 无返回值。 ## 参数
**示例：** - `positive` - 新的正方向按键。
- `negative` - 新的负方向按键。
## 返回值
- 无。
## 示例
```cpp ```cpp
#include <XCEngine/Input/InputAxis.h> axis.SetKeys(XCEngine::Input::KeyCode::Right, XCEngine::Input::KeyCode::Left);
void Example() {
XCEngine::Input::InputAxis object;
// 根据上下文补齐参数后调用 InputAxis::SetKeys(...)。
(void)object;
}
``` ```
## 相关文档 ## 相关文档
- [返回类总览](InputAxis.md) - [返回类型总览](InputAxis.md)
- [返回模块目录](../Input.md) - [Constructor](Constructor.md)

30
docs/api/XCEngine/Input/InputAxis/SetValue.md
View File

@@ -1,31 +1,31 @@
# InputAxis::SetValue # InputAxis::SetValue
设置相关状态或配置。 写入 `InputAxis` 对象内部保存的数值。
```cpp ```cpp
void SetValue(float value); void SetValue(float value);
``` ```
该方法声明于 `XCEngine/Input/InputAxis.h`，当前页面用于固定 `InputAxis` 类目录下的方法级 canonical 路径。 ## 行为说明
**参数：** 当前实现只更新 `m_value`。这不会改变 `InputManager::GetAxis` 或 `GetAxisRaw` 的返回结果，因为管理器当前并不读取该字段。
- `value` - 参数语义详见头文件声明。
**返回：** `void` - 无返回值。 ## 参数
**示例：** - `value` - 要保存的值。
## 返回值
- 无。
## 示例
```cpp ```cpp
#include <XCEngine/Input/InputAxis.h> XCEngine::Input::InputAxis axis;
axis.SetValue(1.0f);
void Example() {
XCEngine::Input::InputAxis object;
// 根据上下文补齐参数后调用 InputAxis::SetValue(...)。
(void)object;
}
``` ```
## 相关文档 ## 相关文档
- [返回类总览](InputAxis.md) - [返回类型总览](InputAxis.md)
- [返回模块目录](../Input.md) - [GetValue](GetValue.md)

79
docs/api/XCEngine/Input/InputEvent/InputEvent.md
View File

@@ -6,34 +6,73 @@
**头文件**: `XCEngine/Input/InputEvent.h` **头文件**: `XCEngine/Input/InputEvent.h`
**描述**: 定义 `XCEngine/Input` 子目录中的 `InputEvent` public API。 **描述**: 定义 `InputManager` 向外分发的键盘、鼠标、文本和触摸事件数据结构。
## 概述 ## 概述
`InputEvent.h` 是 `XCEngine/Input` 子目录 下的 public header，当前页面作为平行目录中的 canonical 总览，用于汇总该头文件暴露的主要声明。 `InputEvent.h` 不是单一事件类，而是一组轻量结构体。它们由 `InputManager::Process*` 方法构造，并通过 `Core::Event` 同步广播给订阅者。
## 声明概览 当前行为特点：
| 声明 | 类型 | 说明 | - 事件回调是同步触发的，发生在 `Process*` 调用线程中。
- 键盘和鼠标事件已有具体生成路径。
- `TouchState` 结构已存在，但当前实现中没有对应的平台填充逻辑。
## 结构体
### `KeyEvent`
| 字段 | 类型 | 说明 |
|------|------|------| |------|------|------|
| `KeyEvent` | `struct` | 头文件中的公开声明。 | | `keyCode` | `KeyCode` | 键值。 |
| `MouseButtonEvent` | `struct` | 头文件中的公开声明。 | | `alt` | `bool` | 事件发生时是否按下 Alt。 |
| `MouseMoveEvent` | `struct` | 头文件中的公开声明。 | | `ctrl` | `bool` | 事件发生时是否按下 Ctrl。 |
| `MouseWheelEvent` | `struct` | 头文件中的公开声明。 | | `shift` | `bool` | 事件发生时是否按下 Shift。 |
| `TextInputEvent` | `struct` | 头文件中的公开声明。 | | `meta` | `bool` | 事件发生时是否按下 Meta。当前 Windows 路径始终为 `false`。 |
| `TouchState` | `struct` | 头文件中的公开声明。 | | `type` | `KeyEvent::Type` | `Down`、`Up` 或 `Repeat`。 |
## 结构体成员 ### `MouseButtonEvent`
| 成员 | 类型 | 描述 | 默认值 | | 字段 | 类型 | 说明 |
|------|------|------|--------| |------|------|------|
| `keyCode` | `KeyCode` | 结构体公开字段。 | - | | `button` | `MouseButton` | 鼠标按键。 |
| `alt` | `bool` | 结构体公开字段。 | - | | `position` | `Math::Vector2` | 事件位置。 |
| `ctrl` | `bool` | 结构体公开字段。 | - | | `type` | `MouseButtonEvent::Type` | `Pressed` 或 `Released`。 |
| `shift` | `bool` | 结构体公开字段。 | - |
| `meta` | `bool` | 结构体公开字段。 | - | ### `MouseMoveEvent`
| 字段 | 类型 | 说明 |
|------|------|------|
| `position` | `Math::Vector2` | 当前鼠标位置。 |
| `delta` | `Math::Vector2` | 相对上一次输入事件的位移。 |
### `MouseWheelEvent`
| 字段 | 类型 | 说明 |
|------|------|------|
| `position` | `Math::Vector2` | 鼠标位置。 |
| `delta` | `float` | 滚轮增量。 |
### `TextInputEvent`
| 字段 | 类型 | 说明 |
|------|------|------|
| `character` | `char` | 输入的单字符。 |
| `text` | `Containers::String` | 当前实现中为长度 1 的字符串。 |
### `TouchState`
| 字段 | 类型 | 说明 |
|------|------|------|
| `touchId` | `int` | 触点 ID。 |
| `position` | `Math::Vector2` | 触点位置。 |
| `deltaPosition` | `Math::Vector2` | 位置变化量。 |
| `deltaTime` | `float` | 与前一状态的时间差。 |
| `tapCount` | `int` | 点击次数。 |
| `phase` | `TouchState::Phase` | `Began`、`Moved`、`Stationary`、`Ended` 或 `Canceled`。 |
## 相关文档 ## 相关文档
- [当前目录](../Input.md) - 返回 `Input` 平行目录 - [当前模块](../Input.md)
- [API 总索引](../../../main.md) - 返回顶层索引 - [InputManager](../InputManager/InputManager.md)
- [Input Flow And Frame Semantics](../../../_guides/Input/Input-Flow-and-Frame-Semantics.md)

31
docs/api/XCEngine/Input/InputManager/ClearAxes.md
View File

@@ -1,30 +1,33 @@
# InputManager::ClearAxes # InputManager::ClearAxes
清空内部数据。 清空当前所有逻辑轴和逻辑按钮映射。
```cpp ```cpp
void ClearAxes(); void ClearAxes();
``` ```
该方法声明于 `XCEngine/Input/InputManager.h`，当前页面用于固定 `InputManager` 类目录下的方法级 canonical 路径。 ## 行为说明
**参数：** 无。 尽管名字叫 `ClearAxes`，当前实现会同时执行：
**返回：** `void` - 无返回值。 - `m_axes.clear()`
- `m_buttons.clear()`
**示例：** 它不会清空键盘、鼠标或事件监听状态。
## 返回值
- 无。
## 示例
```cpp ```cpp
#include <XCEngine/Input/InputManager.h> auto& input = XCEngine::Input::InputManager::Get();
input.ClearAxes();
void Example() {
XCEngine::Input::InputManager object;
// 根据上下文补齐参数后调用 InputManager::ClearAxes(...)。
(void)object;
}
``` ```
## 相关文档 ## 相关文档
- [返回类总览](InputManager.md) - [返回类型总览](InputManager.md)
- [返回模块目录](../Input.md) - [RegisterAxis](RegisterAxis.md)
- [RegisterButton](RegisterButton.md)

23
docs/api/XCEngine/Input/InputManager/Get.md
View File

@@ -1,29 +1,26 @@
# InputManager::Get # InputManager::Get
获取相关状态或对象。 获取进程级全局 `InputManager` 实例。
```cpp ```cpp
static InputManager& Get(); static InputManager& Get();
``` ```
该方法声明于 `XCEngine/Input/InputManager.h`，当前页面用于固定 `InputManager` 类目录下的方法级 canonical 路径。 ## 行为说明
**参数：** 无。 当前实现使用函数内静态对象保存单例。`Get()` 本身不会初始化状态数组，也不会注册默认映射；这些工作要由 [Initialize](Initialize.md) 完成。
**返回：** `InputManager&` - 返回值语义详见头文件声明。 ## 返回值
**示例：** - `InputManager&` - 全局输入管理器引用。
## 示例
```cpp ```cpp
#include <XCEngine/Input/InputManager.h> XCEngine::Input::InputManager& input = XCEngine::Input::InputManager::Get();
void Example() {
auto& instance = XCEngine::Input::InputManager::Get();
(void)instance;
}
``` ```
## 相关文档 ## 相关文档
- [返回类总览](InputManager.md) - [返回类型总览](InputManager.md)
- [返回模块目录](../Input.md) - [Initialize](Initialize.md)

42
docs/api/XCEngine/Input/InputManager/GetAxis.md
View File

@@ -1,31 +1,43 @@
# InputManager::GetAxis # InputManager::GetAxis
获取相关状态或对象。 读取一个具名逻辑轴的当前值。
```cpp ```cpp
float GetAxis(const Containers::String& axisName) const; float GetAxis(const Containers::String& axisName) const;
``` ```
该方法声明于 `XCEngine/Input/InputManager.h`，当前页面用于固定 `InputManager` 类目录下的方法级 canonical 路径。 ## 行为说明
**参数：** 当前实现按以下规则计算返回值：
- `axisName` - 参数语义详见头文件声明。
**返回：** `float` - 返回值语义详见头文件声明。 - 如果找不到该轴，返回 `0.0f`
- 如果正方向键当前按下，结果加 `1.0f`
- 如果负方向键当前按下，结果减 `1.0f`
**示例：** 所以当前结果通常是 `-1.0f`、`0.0f` 或 `1.0f`。如果正负方向同时按下，结果会相互抵消为 `0.0f`。
要特别注意：
- 当前实现没有平滑、插值、重力或灵敏度处理。
- 它不会读取 `InputAxis::GetValue()` 的内部值。
- 默认注册的 `Mouse X` 和 `Mouse Y` 轴当前都绑定为 `KeyCode::None`，因此结果始终为 `0.0f`。
## 参数
- `axisName` - 逻辑轴名称。
## 返回值
- `float` - 当前轴值。
## 示例
```cpp ```cpp
#include <XCEngine/Input/InputManager.h> float horizontal = XCEngine::Input::InputManager::Get().GetAxis("Horizontal");
void Example() {
XCEngine::Input::InputManager object;
// 根据上下文补齐参数后调用 InputManager::GetAxis(...)。
(void)object;
}
``` ```
## 相关文档 ## 相关文档
- [返回类总览](InputManager.md) - [返回类型总览](InputManager.md)
- [返回模块目录](../Input.md) - [GetAxisRaw](GetAxisRaw.md)
- [RegisterAxis](RegisterAxis.md)

34
docs/api/XCEngine/Input/InputManager/GetAxisRaw.md
View File

@@ -1,31 +1,35 @@
# InputManager::GetAxisRaw # InputManager::GetAxisRaw
获取相关状态或对象。 读取一个具名逻辑轴的当前原始值。
```cpp ```cpp
float GetAxisRaw(const Containers::String& axisName) const; float GetAxisRaw(const Containers::String& axisName) const;
``` ```
该方法声明于 `XCEngine/Input/InputManager.h`，当前页面用于固定 `InputManager` 类目录下的方法级 canonical 路径。 ## 行为说明
**参数：** 当前实现与 [GetAxis](GetAxis.md) 最大的区别在于，它检查的是 `IsKeyPressed()`，而不是 `IsKeyDown()`。这意味着：
- `axisName` - 参数语义详见头文件声明。
**返回：** `float` - 返回值语义详见头文件声明。 - 只有在按键“刚按下的那一帧”才会返回 `1.0f` 或 `-1.0f`
- 按住不放跨帧后，结果会回到 `0.0f`
**示例：** 这和很多引擎里“raw axis 仍然表示持续按住的未平滑值”的直觉不同，因此需要特别小心。
## 参数
- `axisName` - 逻辑轴名称。
## 返回值
- `float` - 当前帧的原始边沿值。
## 示例
```cpp ```cpp
#include <XCEngine/Input/InputManager.h> float raw = XCEngine::Input::InputManager::Get().GetAxisRaw("Horizontal");
void Example() {
XCEngine::Input::InputManager object;
// 根据上下文补齐参数后调用 InputManager::GetAxisRaw(...)。
(void)object;
}
``` ```
## 相关文档 ## 相关文档
- [返回类总览](InputManager.md) - [返回类型总览](InputManager.md)
- [返回模块目录](../Input.md) - [GetAxis](GetAxis.md)

34
docs/api/XCEngine/Input/InputManager/GetButton.md
View File

@@ -1,31 +1,37 @@
# InputManager::GetButton # InputManager::GetButton
获取相关状态或对象。 查询一个具名逻辑按钮当前是否按下。
```cpp ```cpp
bool GetButton(const Containers::String& buttonName) const; bool GetButton(const Containers::String& buttonName) const;
``` ```
该方法声明于 `XCEngine/Input/InputManager.h`，当前页面用于固定 `InputManager` 类目录下的方法级 canonical 路径。 ## 行为说明
**参数：** 当前逻辑按钮只是“名字到 `KeyCode`”的映射。这个方法会：
- `buttonName` - 参数语义详见头文件声明。
**返回：** `bool` - 返回值语义详见头文件声明。 1. 查找 `buttonName`
2. 如果找到，则调用 `IsKeyDown(mappedKey)`
3. 如果没找到，则返回 `false`
**示例：** ## 参数
- `buttonName` - 逻辑按钮名称。
## 返回值
- `bool` - 当前是否按下。
## 示例
```cpp ```cpp
#include <XCEngine/Input/InputManager.h> if (XCEngine::Input::InputManager::Get().GetButton("Jump")) {
// ...
void Example() {
XCEngine::Input::InputManager object;
// 根据上下文补齐参数后调用 InputManager::GetButton(...)。
(void)object;
} }
``` ```
## 相关文档 ## 相关文档
- [返回类总览](InputManager.md) - [返回类型总览](InputManager.md)
- [返回模块目录](../Input.md) - [GetButtonDown](GetButtonDown.md)
- [RegisterButton](RegisterButton.md)

32
docs/api/XCEngine/Input/InputManager/GetButtonDown.md
View File

@@ -1,31 +1,35 @@
# InputManager::GetButtonDown # InputManager::GetButtonDown
获取相关状态或对象。 查询一个具名逻辑按钮是否在本帧刚被按下。
```cpp ```cpp
bool GetButtonDown(const Containers::String& buttonName) const; bool GetButtonDown(const Containers::String& buttonName) const;
``` ```
该方法声明于 `XCEngine/Input/InputManager.h`，当前页面用于固定 `InputManager` 类目录下的方法级 canonical 路径。 ## 行为说明
**参数：** 当前实现把逻辑按钮当作 `KeyCode` 别名处理，因此这个方法等价于对映射后的键调用 `IsKeyPressed()`。
- `buttonName` - 参数语义详见头文件声明。
**返回：** `bool` - 返回值语义详见头文件声明。 如果按钮名未注册，返回 `false`。
**示例：** ## 参数
- `buttonName` - 逻辑按钮名称。
## 返回值
- `bool` - 该按钮是否在本帧刚被按下。
## 示例
```cpp ```cpp
#include <XCEngine/Input/InputManager.h> if (XCEngine::Input::InputManager::Get().GetButtonDown("Fire1")) {
// ...
void Example() {
XCEngine::Input::InputManager object;
// 根据上下文补齐参数后调用 InputManager::GetButtonDown(...)。
(void)object;
} }
``` ```
## 相关文档 ## 相关文档
- [返回类总览](InputManager.md) - [返回类型总览](InputManager.md)
- [返回模块目录](../Input.md) - [GetButton](GetButton.md)
- [GetButtonUp](GetButtonUp.md)

31
docs/api/XCEngine/Input/InputManager/GetButtonUp.md
View File

@@ -1,31 +1,32 @@
# InputManager::GetButtonUp # InputManager::GetButtonUp
获取相关状态或对象。 查询一个具名逻辑按钮当前是否处于抬起状态。
```cpp ```cpp
bool GetButtonUp(const Containers::String& buttonName) const; bool GetButtonUp(const Containers::String& buttonName) const;
``` ```
该方法声明于 `XCEngine/Input/InputManager.h`，当前页面用于固定 `InputManager` 类目录下的方法级 canonical 路径。 ## 行为说明
**参数：** 如果按钮名已注册，当前实现会对映射后的键调用 `IsKeyUp()`。如果按钮名未注册，当前实现直接返回 `true`。
- `buttonName` - 参数语义详见头文件声明。
**返回：** `bool` - 返回值语义详见头文件声明。 这个“未注册也算 Up”是当前行为，不一定符合所有上层代码的直觉。
**示例：** ## 参数
- `buttonName` - 逻辑按钮名称。
## 返回值
- `bool` - 当前是否处于抬起状态；未注册按钮也会返回 `true`。
## 示例
```cpp ```cpp
#include <XCEngine/Input/InputManager.h> bool released = XCEngine::Input::InputManager::Get().GetButtonUp("Jump");
void Example() {
XCEngine::Input::InputManager object;
// 根据上下文补齐参数后调用 InputManager::GetButtonUp(...)。
(void)object;
}
``` ```
## 相关文档 ## 相关文档
- [返回类总览](InputManager.md) - [返回类型总览](InputManager.md)
- [返回模块目录](../Input.md) - [GetButton](GetButton.md)

28
docs/api/XCEngine/Input/InputManager/GetMouseDelta.md
View File

@@ -1,30 +1,30 @@
# InputManager::GetMouseDelta # InputManager::GetMouseDelta
获取相关状态或对象。 读取当前帧保存的鼠标位移。
```cpp ```cpp
Math::Vector2 GetMouseDelta() const; Math::Vector2 GetMouseDelta() const;
``` ```
该方法声明于 `XCEngine/Input/InputManager.h`，当前页面用于固定 `InputManager` 类目录下的方法级 canonical 路径。 ## 行为说明
**参数：** 无。 当前实现返回最近一次 [ProcessMouseMove](ProcessMouseMove.md) 写入的 `m_mouseDelta`。它有两个重要特点：
**返回：** `Math::Vector2` - 返回值语义详见头文件声明。 - 不是累加值，而是最近一次输入事件的 delta
- 会在 [Update](Update.md) 时被重置为 `Vector2::Zero()`
**示例：** ## 返回值
- `Math::Vector2` - 当前保存的鼠标位移。
## 示例
```cpp ```cpp
#include <XCEngine/Input/InputManager.h> auto delta = XCEngine::Input::InputManager::Get().GetMouseDelta();
void Example() {
XCEngine::Input::InputManager object;
// 根据上下文补齐参数后调用 InputManager::GetMouseDelta(...)。
(void)object;
}
``` ```
## 相关文档 ## 相关文档
- [返回类总览](InputManager.md) - [返回类型总览](InputManager.md)
- [返回模块目录](../Input.md) - [ProcessMouseMove](ProcessMouseMove.md)
- [Update](Update.md)

26
docs/api/XCEngine/Input/InputManager/GetMousePosition.md
View File

@@ -1,30 +1,28 @@
# InputManager::GetMousePosition # InputManager::GetMousePosition
获取相关状态或对象。 读取当前保存的鼠标位置。
```cpp ```cpp
Math::Vector2 GetMousePosition() const; Math::Vector2 GetMousePosition() const;
``` ```
该方法声明于 `XCEngine/Input/InputManager.h`，当前页面用于固定 `InputManager` 类目录下的方法级 canonical 路径。 ## 行为说明
**参数：** 无。 当前实现直接返回内部 `m_mousePosition`。该值由 [ProcessMouseMove](ProcessMouseMove.md) 或鼠标按钮/滚轮事件携带的位置间接更新。
**返回：** `Math::Vector2` - 返回值语义详见头文件声明。 如果尚未收到任何鼠标输入，默认值通常是零向量。
**示例：** ## 返回值
- `Math::Vector2` - 当前鼠标位置。
## 示例
```cpp ```cpp
#include <XCEngine/Input/InputManager.h> auto pos = XCEngine::Input::InputManager::Get().GetMousePosition();
void Example() {
XCEngine::Input::InputManager object;
// 根据上下文补齐参数后调用 InputManager::GetMousePosition(...)。
(void)object;
}
``` ```
## 相关文档 ## 相关文档
- [返回类总览](InputManager.md) - [返回类型总览](InputManager.md)
- [返回模块目录](../Input.md) - [ProcessMouseMove](ProcessMouseMove.md)

25
docs/api/XCEngine/Input/InputManager/GetMouseScrollDelta.md
View File

@@ -1,30 +1,27 @@
# InputManager::GetMouseScrollDelta # InputManager::GetMouseScrollDelta
获取相关状态或对象。 读取当前帧保存的滚轮增量。
```cpp ```cpp
float GetMouseScrollDelta() const; float GetMouseScrollDelta() const;
``` ```
该方法声明于 `XCEngine/Input/InputManager.h`，当前页面用于固定 `InputManager` 类目录下的方法级 canonical 路径。 ## 行为说明
**参数：** 无。 当前实现返回内部 `m_mouseScrollDelta`。该值在 [ProcessMouseWheel](ProcessMouseWheel.md) 中被直接覆盖，而不是累加，并会在 [Update](Update.md) 时重置为 `0.0f`。
**返回：** `float` - 返回值语义详见头文件声明。 ## 返回值
**示例：** - `float` - 当前帧保存的滚轮增量。
## 示例
```cpp ```cpp
#include <XCEngine/Input/InputManager.h> float scroll = XCEngine::Input::InputManager::Get().GetMouseScrollDelta();
void Example() {
XCEngine::Input::InputManager object;
// 根据上下文补齐参数后调用 InputManager::GetMouseScrollDelta(...)。
(void)object;
}
``` ```
## 相关文档 ## 相关文档
- [返回类总览](InputManager.md) - [返回类型总览](InputManager.md)
- [返回模块目录](../Input.md) - [ProcessMouseWheel](ProcessMouseWheel.md)
- [Update](Update.md)

31
docs/api/XCEngine/Input/InputManager/GetTouch.md
View File

@@ -1,31 +1,32 @@
# InputManager::GetTouch # InputManager::GetTouch
获取相关状态或对象。 读取指定索引的触点状态。
```cpp ```cpp
TouchState GetTouch(int index) const; TouchState GetTouch(int index) const;
``` ```
该方法声明于 `XCEngine/Input/InputManager.h`，当前页面用于固定 `InputManager` 类目录下的方法级 canonical 路径。 ## 行为说明
**参数：** 如果 `index` 合法，当前实现返回 `m_touches[index]` 的拷贝；否则返回默认构造的 `TouchState{}`。
- `index` - 参数语义详见头文件声明。
**返回：** `TouchState` - 返回值语义详见头文件声明。 由于当前公开代码路径并不会填充 `m_touches`，这个接口大多数情况下只会返回默认值。
**示例：** ## 参数
- `index` - 触点索引。
## 返回值
- `TouchState` - 指定触点状态；非法索引时为默认构造值。
## 示例
```cpp ```cpp
#include <XCEngine/Input/InputManager.h> auto touch = XCEngine::Input::InputManager::Get().GetTouch(0);
void Example() {
XCEngine::Input::InputManager object;
// 根据上下文补齐参数后调用 InputManager::GetTouch(...)。
(void)object;
}
``` ```
## 相关文档 ## 相关文档
- [返回类总览](InputManager.md) - [返回类型总览](InputManager.md)
- [返回模块目录](../Input.md) - [GetTouchCount](GetTouchCount.md)

24
docs/api/XCEngine/Input/InputManager/GetTouchCount.md
View File

@@ -1,30 +1,26 @@
# InputManager::GetTouchCount # InputManager::GetTouchCount
获取相关状态或对象。 读取当前已保存的触点数量。
```cpp ```cpp
int GetTouchCount() const; int GetTouchCount() const;
``` ```
该方法声明于 `XCEngine/Input/InputManager.h`，当前页面用于固定 `InputManager` 类目录下的方法级 canonical 路径。 ## 行为说明
**参数：** 无。 当前实现直接返回 `m_touches.size()`。因为现有公开代码路径没有填充触摸状态，所以在当前版本里它通常为 `0`。
**返回：** `int` - 返回值语义详见头文件声明。 ## 返回值
**示例：** - `int` - 当前触点数量。
## 示例
```cpp ```cpp
#include <XCEngine/Input/InputManager.h> int count = XCEngine::Input::InputManager::Get().GetTouchCount();
void Example() {
XCEngine::Input::InputManager object;
// 根据上下文补齐参数后调用 InputManager::GetTouchCount(...)。
(void)object;
}
``` ```
## 相关文档 ## 相关文档
- [返回类总览](InputManager.md) - [返回类型总览](InputManager.md)
- [返回模块目录](../Input.md) - [GetTouch](GetTouch.md)

44
docs/api/XCEngine/Input/InputManager/Initialize.md
View File

@@ -1,31 +1,45 @@
# InputManager::Initialize # InputManager::Initialize
初始化内部状态。 初始化输入状态缓存并注册默认逻辑映射。
```cpp ```cpp
void Initialize(void* platformWindowHandle); void Initialize(void* platformWindowHandle);
``` ```
该方法声明于 `XCEngine/Input/InputManager.h`，当前页面用于固定 `InputManager` 类目录下的方法级 canonical 路径。 ## 行为说明
**参数：** 当前实现是幂等的：如果已经初始化，直接返回。
- `platformWindowHandle` - 参数语义详见头文件声明。
**返回：** `void` - 无返回值。 首次初始化时，它会：
**示例：** - 保存 `platformWindowHandle`
- 分配 256 槽键盘状态数组
- 分配 5 槽鼠标按键状态数组
- 分配 32 槽按钮瞬时状态数组
- 注册默认轴和按钮映射
- 把 `m_initialized` 设为 `true`
当前没有做的事情：
- 不会清空事件监听器
- 不会校验窗口句柄
- 不会启动平台事件循环
## 参数
- `platformWindowHandle` - 平台窗口句柄；当前会保存下来，但 `InputManager` 本身不直接使用它。
## 返回值
- 无。
## 示例
```cpp ```cpp
#include <XCEngine/Input/InputManager.h> XCEngine::Input::InputManager::Get().Initialize(windowHandle);
void Example() {
XCEngine::Input::InputManager object;
// 根据上下文补齐参数后调用 InputManager::Initialize(...)。
(void)object;
}
``` ```
## 相关文档 ## 相关文档
- [返回类总览](InputManager.md) - [返回类型总览](InputManager.md)
- [返回模块目录](../Input.md) - [Shutdown](Shutdown.md)

119
docs/api/XCEngine/Input/InputManager/InputManager.md
View File

@@ -6,58 +6,89 @@
**头文件**: `XCEngine/Input/InputManager.h` **头文件**: `XCEngine/Input/InputManager.h`
**描述**: 定义 `XCEngine/Input` 子目录中的 `InputManager` public API。 **描述**: 保存当前输入状态、提供轮询查询接口，并同步广播输入事件。
## 概述 ## 概述
`InputManager.h` 是 `XCEngine/Input` 子目录 下的 public header，当前页面作为平行目录中的 canonical 总览，用于汇总该头文件暴露的主要声明。 `InputManager` 是 XCEngine 当前输入系统的核心入口。平台层通过 `ProcessKeyDown`、`ProcessMouseMove` 等方法把原始输入送进来；游戏代码、编辑器和测试代码则通过 `IsKeyDown`、`GetAxis`、`OnKeyEvent` 等 API 查询或订阅这些状态。
## 声明概览 它同时承担两种角色：
| 声明 | 类型 | 说明 | - 轮询中心：保存“当前是否按下”“本帧是否刚按下”“本帧鼠标位移”等状态。
|------|------|------| - 事件中心：把输入变化同步广播给订阅者。
| `InputManager` | `class` | 头文件中的公开声明。 |
## 公共方法 ## 生命周期
| 方法 | 描述 | - [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) | 获取相关状态或对象。 | | [Get](Get.md) | 获取全局 `InputManager` 实例。 |
| [Initialize](Initialize.md) | 初始化内部状态。 | | [Initialize](Initialize.md) | 初始化输入状态和默认映射。 |
| [Shutdown](Shutdown.md) | 关闭并清理内部状态。 | | [Shutdown](Shutdown.md) | 清空输入状态与映射。 |
| [Update](Update.md) | 更新运行时状态。 | | [Update](Update.md) | 推进帧边界并清理瞬时状态。 |
| [IsKeyDown](IsKeyDown.md) | 查询当前状态。 | | [IsKeyDown](IsKeyDown.md) | 查询键是否处于按下状态。 |
| [IsKeyUp](IsKeyUp.md) | 查询当前状态。 | | [IsKeyUp](IsKeyUp.md) | 查询键是否处于抬起状态。 |
| [IsKeyPressed](IsKeyPressed.md) | 查询当前状态。 | | [IsKeyPressed](IsKeyPressed.md) | 查询键是否在本帧刚被按下。 |
| [GetMousePosition](GetMousePosition.md) | 获取相关状态或对象。 | | [GetMousePosition](GetMousePosition.md) | 读取当前鼠标位置。 |
| [GetMouseDelta](GetMouseDelta.md) | 获取相关状态或对象。 | | [GetMouseDelta](GetMouseDelta.md) | 读取本帧鼠标位移。 |
| [GetMouseScrollDelta](GetMouseScrollDelta.md) | 获取相关状态或对象。 | | [GetMouseScrollDelta](GetMouseScrollDelta.md) | 读取本帧滚轮增量。 |
| [IsMouseButtonDown](IsMouseButtonDown.md) | 查询当前状态。 | | [IsMouseButtonDown](IsMouseButtonDown.md) | 查询鼠标按键是否按下。 |
| [IsMouseButtonUp](IsMouseButtonUp.md) | 查询当前状态。 | | [IsMouseButtonUp](IsMouseButtonUp.md) | 查询鼠标按键是否抬起。 |
| [IsMouseButtonClicked](IsMouseButtonClicked.md) | 查询当前状态。 | | [IsMouseButtonClicked](IsMouseButtonClicked.md) | 查询鼠标按键是否在本帧刚被按下。 |
| [GetTouchCount](GetTouchCount.md) | 获取相关状态或对象。 | | [GetTouchCount](GetTouchCount.md) | 读取触点数量。 |
| [GetTouch](GetTouch.md) | 获取相关状态或对象。 | | [GetTouch](GetTouch.md) | 读取指定触点状态。 |
| [GetAxis](GetAxis.md) | 获取相关状态或对象。 | | [GetAxis](GetAxis.md) | 读取具名逻辑轴。 |
| [GetAxisRaw](GetAxisRaw.md) | 获取相关状态或对象。 | | [GetAxisRaw](GetAxisRaw.md) | 读取具名逻辑轴的当前原始值。 |
| [GetButton](GetButton.md) | 获取相关状态或对象。 | | [GetButton](GetButton.md) | 查询具名按钮当前是否按下。 |
| [GetButtonDown](GetButtonDown.md) | 获取相关状态或对象。 | | [GetButtonDown](GetButtonDown.md) | 查询具名按钮是否在本帧刚按下。 |
| [GetButtonUp](GetButtonUp.md) | 获取相关状态或对象。 | | [GetButtonUp](GetButtonUp.md) | 查询具名按钮是否处于抬起状态。 |
| [RegisterAxis](RegisterAxis.md) | 注册对象、回调或映射。 | | [RegisterAxis](RegisterAxis.md) | 注册或覆盖一个具名轴。 |
| [RegisterButton](RegisterButton.md) | 注册对象、回调或映射。 | | [RegisterButton](RegisterButton.md) | 注册或覆盖一个具名按钮。 |
| [ClearAxes](ClearAxes.md) | 清空内部数据。 | | [ClearAxes](ClearAxes.md) | 清空轴和按钮映射。 |
| [OnKeyEvent](OnKeyEvent.md) | 公开方法，详见头文件声明。 | | [OnKeyEvent](OnKeyEvent.md) | 获取键盘事件通道。 |
| [OnMouseButton](OnMouseButton.md) | 公开方法，详见头文件声明。 | | [OnMouseButton](OnMouseButton.md) | 获取鼠标按键事件通道。 |
| [OnMouseMove](OnMouseMove.md) | 公开方法，详见头文件声明。 | | [OnMouseMove](OnMouseMove.md) | 获取鼠标移动事件通道。 |
| [OnMouseWheel](OnMouseWheel.md) | 公开方法，详见头文件声明。 | | [OnMouseWheel](OnMouseWheel.md) | 获取鼠标滚轮事件通道。 |
| [OnTextInput](OnTextInput.md) | 公开方法，详见头文件声明。 | | [OnTextInput](OnTextInput.md) | 获取文本输入事件通道。 |
| [ProcessKeyDown](ProcessKeyDown.md) | 公开方法，详见头文件声明。 | | [ProcessKeyDown](ProcessKeyDown.md) | 注入按键按下事件。 |
| [ProcessKeyUp](ProcessKeyUp.md) | 公开方法，详见头文件声明。 | | [ProcessKeyUp](ProcessKeyUp.md) | 注入按键抬起事件。 |
| [ProcessMouseMove](ProcessMouseMove.md) | 公开方法，详见头文件声明。 | | [ProcessMouseMove](ProcessMouseMove.md) | 注入鼠标移动事件。 |
| [ProcessMouseButton](ProcessMouseButton.md) | 公开方法，详见头文件声明。 | | [ProcessMouseButton](ProcessMouseButton.md) | 注入鼠标按键事件。 |
| [ProcessMouseWheel](ProcessMouseWheel.md) | 公开方法，详见头文件声明。 | | [ProcessMouseWheel](ProcessMouseWheel.md) | 注入鼠标滚轮事件。 |
| [ProcessTextInput](ProcessTextInput.md) | 公开方法，详见头文件声明。 | | [ProcessTextInput](ProcessTextInput.md) | 注入文本输入事件。 |
## 相关文档 ## 相关文档
- [当前目录](../Input.md) - 返回 `Input` 平行目录 - [当前模块](../Input.md)
- [API 总索引](../../../main.md) - 返回顶层索引 - [InputAxis](../InputAxis/InputAxis.md)
- [InputEvent](../InputEvent/InputEvent.md)
- [Input Flow And Frame Semantics](../../../_guides/Input/Input-Flow-and-Frame-Semantics.md)

35
docs/api/XCEngine/Input/InputManager/IsKeyDown.md
View File

@@ -1,31 +1,36 @@
# InputManager::IsKeyDown # InputManager::IsKeyDown
查询当前状态。 查询一个键当前是否按下。
```cpp ```cpp
bool IsKeyDown(KeyCode key) const; bool IsKeyDown(KeyCode key) const;
``` ```
该方法声明于 `XCEngine/Input/InputManager.h`，当前页面用于固定 `InputManager` 类目录下的方法级 canonical 路径。 ## 行为说明
**参数：** 当前实现会：
- `key` - 参数语义详见头文件声明。
**返回：** `bool` - 返回值语义详见头文件声明。 - 如果未初始化，返回 `false`
- 把 `KeyCode` 强转成数组下标
- 如果下标越界，返回 `false`
- 否则返回 `m_keyDown[index]`
**示例：** ## 参数
- `key` - 要查询的键。
## 返回值
- `bool` - 当前是否按下。
## 示例
```cpp ```cpp
#include <XCEngine/Input/InputManager.h> bool held = XCEngine::Input::InputManager::Get().IsKeyDown(XCEngine::Input::KeyCode::A);
void Example() {
XCEngine::Input::InputManager object;
// 根据上下文补齐参数后调用 InputManager::IsKeyDown(...)。
(void)object;
}
``` ```
## 相关文档 ## 相关文档
- [返回类总览](InputManager.md) - [返回类型总览](InputManager.md)
- [返回模块目录](../Input.md) - [IsKeyPressed](IsKeyPressed.md)
- [IsKeyUp](IsKeyUp.md)

38
docs/api/XCEngine/Input/InputManager/IsKeyPressed.md
View File

@@ -1,31 +1,39 @@
# InputManager::IsKeyPressed # InputManager::IsKeyPressed
查询当前状态。 查询一个键是否在本帧刚被按下。
```cpp ```cpp
bool IsKeyPressed(KeyCode key) const; bool IsKeyPressed(KeyCode key) const;
``` ```
该方法声明于 `XCEngine/Input/InputManager.h`，当前页面用于固定 `InputManager` 类目录下的方法级 canonical 路径。 ## 行为说明
**参数：** 当前实现判断条件是：
- `key` - 参数语义详见头文件声明。
**返回：** `bool` - 返回值语义详见头文件声明。
**示例：**
```cpp ```cpp
#include <XCEngine/Input/InputManager.h> m_keyDownThisFrame[index] && !m_keyDownLastFrame[index]
```
void Example() { 所以它表示的是“从上一帧到当前帧的按下边沿”。要得到正确结果，必须保证 [Update](Update.md) 每帧只在固定边界调用一次。
XCEngine::Input::InputManager object;
// 根据上下文补齐参数后调用 InputManager::IsKeyPressed(...)。 ## 参数
(void)object;
- `key` - 要查询的键。
## 返回值
- `bool` - 当前帧是否刚按下。
## 示例
```cpp
if (XCEngine::Input::InputManager::Get().IsKeyPressed(XCEngine::Input::KeyCode::Space)) {
// ...
} }
``` ```
## 相关文档 ## 相关文档
- [返回类总览](InputManager.md) - [返回类型总览](InputManager.md)
- [返回模块目录](../Input.md) - [Update](Update.md)
- [IsKeyDown](IsKeyDown.md)

30
docs/api/XCEngine/Input/InputManager/IsKeyUp.md
View File

@@ -1,31 +1,29 @@
# InputManager::IsKeyUp # InputManager::IsKeyUp
查询当前状态。 查询一个键当前是否处于抬起状态。
```cpp ```cpp
bool IsKeyUp(KeyCode key) const; bool IsKeyUp(KeyCode key) const;
``` ```
该方法声明于 `XCEngine/Input/InputManager.h`，当前页面用于固定 `InputManager` 类目录下的方法级 canonical 路径。 ## 行为说明
**参数：** 当前实现有一个很宽松的定义：
- `key` - 参数语义详见头文件声明。
**返回：** `bool` - 返回值语义详见头文件声明。 - 如果管理器未初始化，返回 `true`
- 否则返回 `!IsKeyDown(key)`
**示例：** 因此对于未初始化或未识别的键，它都会被视为 “Up”。
```cpp ## 参数
#include <XCEngine/Input/InputManager.h>
void Example() { - `key` - 要查询的键。
XCEngine::Input::InputManager object;
// 根据上下文补齐参数后调用 InputManager::IsKeyUp(...)。 ## 返回值
(void)object;
} - `bool` - 当前是否抬起。
```
## 相关文档 ## 相关文档
- [返回类总览](InputManager.md) - [返回类型总览](InputManager.md)
- [返回模块目录](../Input.md) - [IsKeyDown](IsKeyDown.md)

34
docs/api/XCEngine/Input/InputManager/IsMouseButtonClicked.md
View File

@@ -1,31 +1,31 @@
# InputManager::IsMouseButtonClicked # InputManager::IsMouseButtonClicked
查询当前状态。 查询鼠标按键是否在本帧刚被按下。
```cpp ```cpp
bool IsMouseButtonClicked(MouseButton button) const; bool IsMouseButtonClicked(MouseButton button) const;
``` ```
该方法声明于 `XCEngine/Input/InputManager.h`，当前页面用于固定 `InputManager` 类目录下的方法级 canonical 路径。 ## 行为说明
**参数：** 当前实现与 `IsKeyPressed` 类似，判断条件是：
- `button` - 参数语义详见头文件声明。
**返回：** `bool` - 返回值语义详见头文件声明。
**示例：**
```cpp ```cpp
#include <XCEngine/Input/InputManager.h> m_mouseButtonDownThisFrame[index] && !m_mouseButtonDownLastFrame[index]
void Example() {
XCEngine::Input::InputManager object;
// 根据上下文补齐参数后调用 InputManager::IsMouseButtonClicked(...)。
(void)object;
}
``` ```
它表示的是“本帧按下边沿”，而不是完整的点击手势。
## 参数
- `button` - 要查询的鼠标按键。
## 返回值
- `bool` - 当前帧是否刚被按下。
## 相关文档 ## 相关文档
- [返回类总览](InputManager.md) - [返回类型总览](InputManager.md)
- [返回模块目录](../Input.md) - [IsMouseButtonDown](IsMouseButtonDown.md)
- [Update](Update.md)

25
docs/api/XCEngine/Input/InputManager/IsMouseButtonDown.md
View File

@@ -1,31 +1,24 @@
# InputManager::IsMouseButtonDown # InputManager::IsMouseButtonDown
查询当前状态。 查询鼠标按键当前是否按下。
```cpp ```cpp
bool IsMouseButtonDown(MouseButton button) const; bool IsMouseButtonDown(MouseButton button) const;
``` ```
该方法声明于 `XCEngine/Input/InputManager.h`，当前页面用于固定 `InputManager` 类目录下的方法级 canonical 路径。 ## 行为说明
**参数：** 如果未初始化或按钮索引越界，当前实现返回 `false`。否则返回 `m_mouseButtonDown[index]`。
- `button` - 参数语义详见头文件声明。
**返回：** `bool` - 返回值语义详见头文件声明。 ## 参数
**示例：** - `button` - 要查询的鼠标按键。
```cpp ## 返回值
#include <XCEngine/Input/InputManager.h>
void Example() { - `bool` - 当前是否按下。
XCEngine::Input::InputManager object;
// 根据上下文补齐参数后调用 InputManager::IsMouseButtonDown(...)。
(void)object;
}
```
## 相关文档 ## 相关文档
- [返回类总览](InputManager.md) - [返回类型总览](InputManager.md)
- [返回模块目录](../Input.md) - [IsMouseButtonUp](IsMouseButtonUp.md)

25
docs/api/XCEngine/Input/InputManager/IsMouseButtonUp.md
View File

@@ -1,31 +1,24 @@
# InputManager::IsMouseButtonUp # InputManager::IsMouseButtonUp
查询当前状态。 查询鼠标按键当前是否处于抬起状态。
```cpp ```cpp
bool IsMouseButtonUp(MouseButton button) const; bool IsMouseButtonUp(MouseButton button) const;
``` ```
该方法声明于 `XCEngine/Input/InputManager.h`，当前页面用于固定 `InputManager` 类目录下的方法级 canonical 路径。 ## 行为说明
**参数：** 如果未初始化，当前实现返回 `true`；否则返回 `!IsMouseButtonDown(button)`。这和键盘的 `IsKeyUp` 语义一致。
- `button` - 参数语义详见头文件声明。
**返回：** `bool` - 返回值语义详见头文件声明。 ## 参数
**示例：** - `button` - 要查询的鼠标按键。
```cpp ## 返回值
#include <XCEngine/Input/InputManager.h>
void Example() { - `bool` - 当前是否抬起。
XCEngine::Input::InputManager object;
// 根据上下文补齐参数后调用 InputManager::IsMouseButtonUp(...)。
(void)object;
}
```
## 相关文档 ## 相关文档
- [返回类总览](InputManager.md) - [返回类型总览](InputManager.md)
- [返回模块目录](../Input.md) - [IsMouseButtonDown](IsMouseButtonDown.md)

32
docs/api/XCEngine/Input/InputManager/OnKeyEvent.md
View File

@@ -1,30 +1,34 @@
# InputManager::OnKeyEvent # InputManager::OnKeyEvent
公开方法，详见头文件声明。 获取键盘事件通道。
```cpp ```cpp
Core::Event<const KeyEvent&>& OnKeyEvent(); Core::Event<const KeyEvent&>& OnKeyEvent();
``` ```
该方法声明于 `XCEngine/Input/InputManager.h`，当前页面用于固定 `InputManager` 类目录下的方法级 canonical 路径。 ## 行为说明
**参数：** 无。 返回内部 `Core::Event<const KeyEvent&>` 引用。当前事件会在 [ProcessKeyDown](ProcessKeyDown.md) 和 [ProcessKeyUp](ProcessKeyUp.md) 中同步触发。
**返回：** `Core::Event<const KeyEvent&>&` - 返回值语义详见头文件声明。 需要注意：
**示例：** - 回调执行线程就是调用 `Process*` 的线程。
- 当前 `Shutdown()` 不会清空这个事件对象中的监听器。
## 返回值
- `Core::Event<const KeyEvent&>&` - 键盘事件通道。
## 示例
```cpp ```cpp
#include <XCEngine/Input/InputManager.h> auto id = XCEngine::Input::InputManager::Get().OnKeyEvent().Subscribe(
[](const XCEngine::Input::KeyEvent& e) {}
void Example() { );
XCEngine::Input::InputManager object;
// 根据上下文补齐参数后调用 InputManager::OnKeyEvent(...)。
(void)object;
}
``` ```
## 相关文档 ## 相关文档
- [返回类总览](InputManager.md) - [返回类型总览](InputManager.md)
- [返回模块目录](../Input.md) - [ProcessKeyDown](ProcessKeyDown.md)
- [ProcessKeyUp](ProcessKeyUp.md)

24
docs/api/XCEngine/Input/InputManager/OnMouseButton.md
View File

@@ -1,30 +1,20 @@
# InputManager::OnMouseButton # InputManager::OnMouseButton
公开方法，详见头文件声明。 获取鼠标按键事件通道。
```cpp ```cpp
Core::Event<const MouseButtonEvent&>& OnMouseButton(); Core::Event<const MouseButtonEvent&>& OnMouseButton();
``` ```
该方法声明于 `XCEngine/Input/InputManager.h`，当前页面用于固定 `InputManager` 类目录下的方法级 canonical 路径。 ## 行为说明
**参数：** 无。 当前事件会在 [ProcessMouseButton](ProcessMouseButton.md) 中同步触发。它适合 UI、编辑器工具和测试代码订阅鼠标按键变化。
**返回：** `Core::Event<const MouseButtonEvent&>&` - 返回值语义详见头文件声明。 ## 返回值
**示例：** - `Core::Event<const MouseButtonEvent&>&` - 鼠标按键事件通道。
```cpp
#include <XCEngine/Input/InputManager.h>
void Example() {
XCEngine::Input::InputManager object;
// 根据上下文补齐参数后调用 InputManager::OnMouseButton(...)。
(void)object;
}
```
## 相关文档 ## 相关文档
- [返回类总览](InputManager.md) - [返回类型总览](InputManager.md)
- [返回模块目录](../Input.md) - [ProcessMouseButton](ProcessMouseButton.md)

24
docs/api/XCEngine/Input/InputManager/OnMouseMove.md
View File

@@ -1,30 +1,20 @@
# InputManager::OnMouseMove # InputManager::OnMouseMove
公开方法，详见头文件声明。 获取鼠标移动事件通道。
```cpp ```cpp
Core::Event<const MouseMoveEvent&>& OnMouseMove(); Core::Event<const MouseMoveEvent&>& OnMouseMove();
``` ```
该方法声明于 `XCEngine/Input/InputManager.h`，当前页面用于固定 `InputManager` 类目录下的方法级 canonical 路径。 ## 行为说明
**参数：** 无。 当前事件会在 [ProcessMouseMove](ProcessMouseMove.md) 中同步触发，回调里可以直接读取本次输入事件的位置和 delta。
**返回：** `Core::Event<const MouseMoveEvent&>&` - 返回值语义详见头文件声明。 ## 返回值
**示例：** - `Core::Event<const MouseMoveEvent&>&` - 鼠标移动事件通道。
```cpp
#include <XCEngine/Input/InputManager.h>
void Example() {
XCEngine::Input::InputManager object;
// 根据上下文补齐参数后调用 InputManager::OnMouseMove(...)。
(void)object;
}
```
## 相关文档 ## 相关文档
- [返回类总览](InputManager.md) - [返回类型总览](InputManager.md)
- [返回模块目录](../Input.md) - [ProcessMouseMove](ProcessMouseMove.md)

24
docs/api/XCEngine/Input/InputManager/OnMouseWheel.md
View File

@@ -1,30 +1,20 @@
# InputManager::OnMouseWheel # InputManager::OnMouseWheel
公开方法，详见头文件声明。 获取鼠标滚轮事件通道。
```cpp ```cpp
Core::Event<const MouseWheelEvent&>& OnMouseWheel(); Core::Event<const MouseWheelEvent&>& OnMouseWheel();
``` ```
该方法声明于 `XCEngine/Input/InputManager.h`，当前页面用于固定 `InputManager` 类目录下的方法级 canonical 路径。 ## 行为说明
**参数：** 无。 当前事件会在 [ProcessMouseWheel](ProcessMouseWheel.md) 中同步触发。它和 `GetMouseScrollDelta` 的区别在于：事件可以立即响应每次滚轮输入，而轮询接口只保留当前保存的一个 delta。
**返回：** `Core::Event<const MouseWheelEvent&>&` - 返回值语义详见头文件声明。 ## 返回值
**示例：** - `Core::Event<const MouseWheelEvent&>&` - 鼠标滚轮事件通道。
```cpp
#include <XCEngine/Input/InputManager.h>
void Example() {
XCEngine::Input::InputManager object;
// 根据上下文补齐参数后调用 InputManager::OnMouseWheel(...)。
(void)object;
}
```
## 相关文档 ## 相关文档
- [返回类总览](InputManager.md) - [返回类型总览](InputManager.md)
- [返回模块目录](../Input.md) - [ProcessMouseWheel](ProcessMouseWheel.md)

24
docs/api/XCEngine/Input/InputManager/OnTextInput.md
View File

@@ -1,30 +1,20 @@
# InputManager::OnTextInput # InputManager::OnTextInput
公开方法，详见头文件声明。 获取文本输入事件通道。
```cpp ```cpp
Core::Event<const TextInputEvent&>& OnTextInput(); Core::Event<const TextInputEvent&>& OnTextInput();
``` ```
该方法声明于 `XCEngine/Input/InputManager.h`，当前页面用于固定 `InputManager` 类目录下的方法级 canonical 路径。 ## 行为说明
**参数：** 无。 当前事件会在 [ProcessTextInput](ProcessTextInput.md) 中同步触发。它适合接 UI 输入框、控制台和编辑器文本输入，而不是通用按键绑定逻辑。
**返回：** `Core::Event<const TextInputEvent&>&` - 返回值语义详见头文件声明。 ## 返回值
**示例：** - `Core::Event<const TextInputEvent&>&` - 文本输入事件通道。
```cpp
#include <XCEngine/Input/InputManager.h>
void Example() {
XCEngine::Input::InputManager object;
// 根据上下文补齐参数后调用 InputManager::OnTextInput(...)。
(void)object;
}
```
## 相关文档 ## 相关文档
- [返回类总览](InputManager.md) - [返回类型总览](InputManager.md)
- [返回模块目录](../Input.md) - [ProcessTextInput](ProcessTextInput.md)

43
docs/api/XCEngine/Input/InputManager/ProcessKeyDown.md
View File

@@ -1,36 +1,37 @@
# InputManager::ProcessKeyDown # InputManager::ProcessKeyDown
公开方法，详见头文件声明。 向输入系统注入一个按键按下事件。
```cpp ```cpp
void ProcessKeyDown(KeyCode key, bool repeat, bool alt, bool ctrl, bool shift, bool meta); void ProcessKeyDown(KeyCode key, bool repeat, bool alt, bool ctrl, bool shift, bool meta);
``` ```
该方法声明于 `XCEngine/Input/InputManager.h`，当前页面用于固定 `InputManager` 类目录下的方法级 canonical 路径。 ## 行为说明
**参数：** 当前实现会：
- `key` - 参数语义详见头文件声明。
- `repeat` - 参数语义详见头文件声明。
- `alt` - 参数语义详见头文件声明。
- `ctrl` - 参数语义详见头文件声明。
- `shift` - 参数语义详见头文件声明。
- `meta` - 参数语义详见头文件声明。
**返回：** `void` - 无返回值。 - 如果未初始化或键索引越界，直接返回
- 把 `m_keyDown[index]` 设为 `true`
- 把 `m_keyDownThisFrame[index]` 设为 `true`
- 构造 `KeyEvent`
- 如果 `repeat` 为 `true`，事件类型设为 `Repeat`，否则为 `Down`
- 同步触发 `m_onKeyEvent`
**示例：** ## 参数
```cpp - `key` - 键值。
#include <XCEngine/Input/InputManager.h> - `repeat` - 是否为重复按键事件。
- `alt` - Alt 修饰键状态。
- `ctrl` - Ctrl 修饰键状态。
- `shift` - Shift 修饰键状态。
- `meta` - Meta 修饰键状态。
void Example() { ## 返回值
XCEngine::Input::InputManager object;
// 根据上下文补齐参数后调用 InputManager::ProcessKeyDown(...)。 - 无。
(void)object;
}
```
## 相关文档 ## 相关文档
- [返回类总览](InputManager.md) - [返回类型总览](InputManager.md)
- [返回模块目录](../Input.md) - [OnKeyEvent](OnKeyEvent.md)
- [ProcessKeyUp](ProcessKeyUp.md)

41
docs/api/XCEngine/Input/InputManager/ProcessKeyUp.md
View File

@@ -1,35 +1,36 @@
# InputManager::ProcessKeyUp # InputManager::ProcessKeyUp
公开方法，详见头文件声明。 向输入系统注入一个按键抬起事件。
```cpp ```cpp
void ProcessKeyUp(KeyCode key, bool alt, bool ctrl, bool shift, bool meta); void ProcessKeyUp(KeyCode key, bool alt, bool ctrl, bool shift, bool meta);
``` ```
该方法声明于 `XCEngine/Input/InputManager.h`，当前页面用于固定 `InputManager` 类目录下的方法级 canonical 路径。 ## 行为说明
**参数：** 当前实现会：
- `key` - 参数语义详见头文件声明。
- `alt` - 参数语义详见头文件声明。
- `ctrl` - 参数语义详见头文件声明。
- `shift` - 参数语义详见头文件声明。
- `meta` - 参数语义详见头文件声明。
**返回：** `void` - 无返回值。 - 如果未初始化或键索引越界，直接返回
- 把 `m_keyDown[index]` 设为 `false`
- 构造 `KeyEvent`，类型固定为 `KeyEvent::Up`
- 同步触发 `m_onKeyEvent`
**示例：** 当前没有单独的 “key up this frame” 标志位；抬起后，`IsKeyUp` 会立即通过 `!IsKeyDown(key)` 成立。
```cpp ## 参数
#include <XCEngine/Input/InputManager.h>
void Example() { - `key` - 键值。
XCEngine::Input::InputManager object; - `alt` - Alt 修饰键状态。
// 根据上下文补齐参数后调用 InputManager::ProcessKeyUp(...)。 - `ctrl` - Ctrl 修饰键状态。
(void)object; - `shift` - Shift 修饰键状态。
} - `meta` - Meta 修饰键状态。
```
## 返回值
- 无。
## 相关文档 ## 相关文档
- [返回类总览](InputManager.md) - [返回类型总览](InputManager.md)
- [返回模块目录](../Input.md) - [ProcessKeyDown](ProcessKeyDown.md)
- [OnKeyEvent](OnKeyEvent.md)

40
docs/api/XCEngine/Input/InputManager/ProcessMouseButton.md
View File

@@ -1,34 +1,36 @@
# InputManager::ProcessMouseButton # InputManager::ProcessMouseButton
公开方法，详见头文件声明。 向输入系统注入一个鼠标按键事件。
```cpp ```cpp
void ProcessMouseButton(MouseButton button, bool pressed, int x, int y); void ProcessMouseButton(MouseButton button, bool pressed, int x, int y);
``` ```
该方法声明于 `XCEngine/Input/InputManager.h`，当前页面用于固定 `InputManager` 类目录下的方法级 canonical 路径。 ## 行为说明
**参数：** 当前实现会：
- `button` - 参数语义详见头文件声明。
- `pressed` - 参数语义详见头文件声明。
- `x` - 参数语义详见头文件声明。
- `y` - 参数语义详见头文件声明。
**返回：** `void` - 无返回值。 - 如果未初始化或按钮索引越界，直接返回
- 把 `m_mouseButtonDown[index]` 更新为 `pressed`
- 只有在 `pressed == true` 时，才把 `m_mouseButtonDownThisFrame[index]` 设为 `true`
- 构造 `MouseButtonEvent`
- 同步触发 `m_onMouseButton`
**示例：** 这意味着当前实现只显式记录“按下边沿”，没有单独的 “mouse up this frame” 缓存。
```cpp ## 参数
#include <XCEngine/Input/InputManager.h>
void Example() { - `button` - 鼠标按键。
XCEngine::Input::InputManager object; - `pressed` - `true` 表示按下，`false` 表示释放。
// 根据上下文补齐参数后调用 InputManager::ProcessMouseButton(...)。 - `x` - 事件位置 X。
(void)object; - `y` - 事件位置 Y。
}
``` ## 返回值
- 无。
## 相关文档 ## 相关文档
- [返回类总览](InputManager.md) - [返回类型总览](InputManager.md)
- [返回模块目录](../Input.md) - [OnMouseButton](OnMouseButton.md)
- [IsMouseButtonClicked](IsMouseButtonClicked.md)

40
docs/api/XCEngine/Input/InputManager/ProcessMouseMove.md
View File

@@ -1,34 +1,36 @@
# InputManager::ProcessMouseMove # InputManager::ProcessMouseMove
公开方法，详见头文件声明。 向输入系统注入一个鼠标移动事件。
```cpp ```cpp
void ProcessMouseMove(int x, int y, int deltaX, int deltaY); void ProcessMouseMove(int x, int y, int deltaX, int deltaY);
``` ```
该方法声明于 `XCEngine/Input/InputManager.h`，当前页面用于固定 `InputManager` 类目录下的方法级 canonical 路径。 ## 行为说明
**参数：** 当前实现会：
- `x` - 参数语义详见头文件声明。
- `y` - 参数语义详见头文件声明。
- `deltaX` - 参数语义详见头文件声明。
- `deltaY` - 参数语义详见头文件声明。
**返回：** `void` - 无返回值。 - 如果未初始化，直接返回
- 更新 `m_mousePosition`
- 更新 `m_mouseDelta`
- 构造 `MouseMoveEvent`
- 同步触发 `m_onMouseMove`
**示例：** 它不会累积一帧内的多次移动量，`m_mouseDelta` 始终是最近一次写入的值。
```cpp ## 参数
#include <XCEngine/Input/InputManager.h>
void Example() { - `x` - 当前鼠标位置 X。
XCEngine::Input::InputManager object; - `y` - 当前鼠标位置 Y。
// 根据上下文补齐参数后调用 InputManager::ProcessMouseMove(...)。 - `deltaX` - 相对位移 X。
(void)object; - `deltaY` - 相对位移 Y。
}
``` ## 返回值
- 无。
## 相关文档 ## 相关文档
- [返回类总览](InputManager.md) - [返回类型总览](InputManager.md)
- [返回模块目录](../Input.md) - [OnMouseMove](OnMouseMove.md)
- [GetMouseDelta](GetMouseDelta.md)

37
docs/api/XCEngine/Input/InputManager/ProcessMouseWheel.md
View File

@@ -1,33 +1,34 @@
# InputManager::ProcessMouseWheel # InputManager::ProcessMouseWheel
公开方法，详见头文件声明。 向输入系统注入一个鼠标滚轮事件。
```cpp ```cpp
void ProcessMouseWheel(float delta, int x, int y); void ProcessMouseWheel(float delta, int x, int y);
``` ```
该方法声明于 `XCEngine/Input/InputManager.h`，当前页面用于固定 `InputManager` 类目录下的方法级 canonical 路径。 ## 行为说明
**参数：** 当前实现会：
- `delta` - 参数语义详见头文件声明。
- `x` - 参数语义详见头文件声明。
- `y` - 参数语义详见头文件声明。
**返回：** `void` - 无返回值。 - 如果未初始化，直接返回
- 用 `delta` 覆盖 `m_mouseScrollDelta`
- 构造 `MouseWheelEvent`
- 同步触发 `m_onMouseWheel`
**示例：** 它不会把多次滚轮输入累加到当前帧总量中。
```cpp ## 参数
#include <XCEngine/Input/InputManager.h>
void Example() { - `delta` - 滚轮增量。
XCEngine::Input::InputManager object; - `x` - 鼠标位置 X。
// 根据上下文补齐参数后调用 InputManager::ProcessMouseWheel(...)。 - `y` - 鼠标位置 Y。
(void)object;
} ## 返回值
```
- 无。
## 相关文档 ## 相关文档
- [返回类总览](InputManager.md) - [返回类型总览](InputManager.md)
- [返回模块目录](../Input.md) - [OnMouseWheel](OnMouseWheel.md)
- [GetMouseScrollDelta](GetMouseScrollDelta.md)

33
docs/api/XCEngine/Input/InputManager/ProcessTextInput.md
View File

@@ -1,31 +1,32 @@
# InputManager::ProcessTextInput # InputManager::ProcessTextInput
公开方法，详见头文件声明。 向输入系统注入一个文本输入事件。
```cpp ```cpp
void ProcessTextInput(char c); void ProcessTextInput(char c);
``` ```
该方法声明于 `XCEngine/Input/InputManager.h`，当前页面用于固定 `InputManager` 类目录下的方法级 canonical 路径。 ## 行为说明
**参数：** 当前实现会：
- `c` - 参数语义详见头文件声明。
**返回：** `void` - 无返回值。 - 如果未初始化，直接返回
- 构造 `TextInputEvent`
- 把 `character` 设为 `c`
- 把 `text` 构造成长度为 1 的 `Containers::String`
- 同步触发 `m_onTextInput`
**示例：** 它适合处理字符输入，而不是通用按键状态。
```cpp ## 参数
#include <XCEngine/Input/InputManager.h>
void Example() { - `c` - 输入字符。
XCEngine::Input::InputManager object;
// 根据上下文补齐参数后调用 InputManager::ProcessTextInput(...)。 ## 返回值
(void)object;
} - 无。
```
## 相关文档 ## 相关文档
- [返回类总览](InputManager.md) - [返回类型总览](InputManager.md)
- [返回模块目录](../Input.md) - [OnTextInput](OnTextInput.md)

38
docs/api/XCEngine/Input/InputManager/RegisterAxis.md
View File

@@ -1,31 +1,35 @@
# InputManager::RegisterAxis # InputManager::RegisterAxis
注册对象、回调或映射。 注册或覆盖一个具名逻辑轴。
```cpp ```cpp
void RegisterAxis(const InputAxis& axis); void RegisterAxis(const InputAxis& axis);
``` ```
该方法声明于 `XCEngine/Input/InputManager.h`，当前页面用于固定 `InputManager` 类目录下的方法级 canonical 路径。 ## 行为说明
**参数：** 当前实现会执行：
- `axis` - 参数语义详见头文件声明。
**返回：** `void` - 无返回值。
**示例：**
```cpp ```cpp
#include <XCEngine/Input/InputManager.h> m_axes[axis.GetName()] = axis;
void Example() {
XCEngine::Input::InputManager object;
// 根据上下文补齐参数后调用 InputManager::RegisterAxis(...)。
(void)object;
}
``` ```
因此：
- 同名轴会被覆盖
- `InputAxis` 会按值复制进管理器
- 后续再修改原始 `axis` 对象不会影响管理器中的副本
## 参数
- `axis` - 轴配置对象。
## 返回值
- 无。
## 相关文档 ## 相关文档
- [返回类总览](InputManager.md) - [返回类型总览](InputManager.md)
- [返回模块目录](../Input.md) - [GetAxis](GetAxis.md)
- [ClearAxes](ClearAxes.md)

28
docs/api/XCEngine/Input/InputManager/RegisterButton.md
View File

@@ -1,32 +1,26 @@
# InputManager::RegisterButton # InputManager::RegisterButton
注册对象、回调或映射。 注册或覆盖一个具名逻辑按钮。
```cpp ```cpp
void RegisterButton(const Containers::String& name, KeyCode key); void RegisterButton(const Containers::String& name, KeyCode key);
``` ```
该方法声明于 `XCEngine/Input/InputManager.h`，当前页面用于固定 `InputManager` 类目录下的方法级 canonical 路径。 ## 行为说明
**参数：** 当前实现只保存 `name -> key` 的映射关系，不会创建更复杂的动作状态机。逻辑按钮本质上只是一个有名字的 `KeyCode` 别名。
- `name` - 参数语义详见头文件声明。
- `key` - 参数语义详见头文件声明。
**返回：** `void` - 无返回值。 ## 参数
**示例：** - `name` - 逻辑按钮名称。
- `key` - 对应的按键。
```cpp ## 返回值
#include <XCEngine/Input/InputManager.h>
void Example() { - 无。
XCEngine::Input::InputManager object;
// 根据上下文补齐参数后调用 InputManager::RegisterButton(...)。
(void)object;
}
```
## 相关文档 ## 相关文档
- [返回类总览](InputManager.md) - [返回类型总览](InputManager.md)
- [返回模块目录](../Input.md) - [GetButton](GetButton.md)
- [ClearAxes](ClearAxes.md)

34
docs/api/XCEngine/Input/InputManager/Shutdown.md
View File

@@ -1,30 +1,34 @@
# InputManager::Shutdown # InputManager::Shutdown
关闭并清理内部状态。 清空输入状态缓存和逻辑映射。
```cpp ```cpp
void Shutdown(); void Shutdown();
``` ```
该方法声明于 `XCEngine/Input/InputManager.h`，当前页面用于固定 `InputManager` 类目录下的方法级 canonical 路径。 ## 行为说明
**参数：** 无。 当前实现只有在已初始化时才会执行关闭逻辑。它会清空：
**返回：** `void` - 无返回值。 - 键盘状态数组
- 鼠标按键状态数组
- 轴映射
- 按钮映射
- 按钮瞬时状态数组
**示例：** 然后把 `m_platformWindowHandle` 置空，并把 `m_initialized` 设为 `false`。
```cpp 当前不会清空：
#include <XCEngine/Input/InputManager.h>
void Example() { - 事件监听器
XCEngine::Input::InputManager object; - `m_touches`
// 根据上下文补齐参数后调用 InputManager::Shutdown(...)。 - 鼠标位置缓存
(void)object;
} ## 返回值
```
- 无。
## 相关文档 ## 相关文档
- [返回类总览](InputManager.md) - [返回类型总览](InputManager.md)
- [返回模块目录](../Input.md) - [Initialize](Initialize.md)

37
docs/api/XCEngine/Input/InputManager/Update.md
View File

@@ -1,31 +1,36 @@
# InputManager::Update # InputManager::Update
更新运行时状态。 推进输入系统的帧边界并清理瞬时状态。
```cpp ```cpp
void Update(float deltaTime); void Update(float deltaTime);
``` ```
该方法声明于 `XCEngine/Input/InputManager.h`，当前页面用于固定 `InputManager` 类目录下的方法级 canonical 路径。 ## 行为说明
**参数：** 当前实现如果未初始化则直接返回。否则会：
- `deltaTime` - 参数语义详见头文件声明。
**返回：** `void` - 无返回值。 - 把 `m_keyDownThisFrame` 复制到 `m_keyDownLastFrame`
- 清空并重建 `m_keyDownThisFrame`
- 把 `m_mouseButtonDownThisFrame` 复制到 `m_mouseButtonDownLastFrame`
- 清空并重建 `m_mouseButtonDownThisFrame`
- 把 `m_buttonDownThisFrame` 复制到 `m_buttonDownLastFrame`
- 清空并重建 `m_buttonDownThisFrame`
- 把 `m_mouseDelta` 重置为零向量
- 把 `m_mouseScrollDelta` 重置为 `0.0f`
**示例：** 当前 `deltaTime` 参数没有被使用。
```cpp ## 参数
#include <XCEngine/Input/InputManager.h>
void Example() { - `deltaTime` - 当前未使用，但保留在接口中。
XCEngine::Input::InputManager object;
// 根据上下文补齐参数后调用 InputManager::Update(...)。 ## 返回值
(void)object;
} - 无。
```
## 相关文档 ## 相关文档
- [返回类总览](InputManager.md) - [返回类型总览](InputManager.md)
- [返回模块目录](../Input.md) - [IsKeyPressed](IsKeyPressed.md)
- [IsMouseButtonClicked](IsMouseButtonClicked.md)

24
docs/api/XCEngine/Input/InputModule/Destructor.md
View File

@@ -1,29 +1,19 @@
# InputModule::~InputModule() # InputModule::Destructor
销毁对象并释放相关资源。 以基类指针安全销毁平台输入后端。
```cpp ```cpp
virtual ~InputModule() = default; virtual ~InputModule() = default;
``` ```
该方法声明于 `XCEngine/Input/InputModule.h`，当前页面用于固定 `InputModule` 类目录下的方法级 canonical 路径。 ## 行为说明
**参数：** 无。 这是虚析构函数，保证平台实现类可以通过 `InputModule*` 安全释放。当前接口本身没有默认清理逻辑，具体资源释放由派生类实现负责。
**返回：** `void` - 无返回值。 ## 返回值
**示例：** - 无。
```cpp
#include <XCEngine/Input/InputModule.h>
void Example() {
XCEngine::Input::InputModule object;
// 对象离开作用域时会自动触发析构。
}
```
## 相关文档 ## 相关文档
- [返回类总览](InputModule.md) - [返回类型总览](InputModule.md)
- [返回模块目录](../Input.md)

33
docs/api/XCEngine/Input/InputModule/HandleMessage.md
View File

@@ -1,34 +1,29 @@
# InputModule::HandleMessage # InputModule::HandleMessage
公开方法，详见头文件声明。 处理一条平台窗口消息并把它翻译成引擎输入事件。
```cpp ```cpp
virtual void HandleMessage(size_t hwnd, unsigned int msg, size_t wParam, size_t lParam) = 0; virtual void HandleMessage(size_t hwnd, unsigned int msg, size_t wParam, size_t lParam) = 0;
``` ```
该方法声明于 `XCEngine/Input/InputModule.h`，当前页面用于固定 `InputModule` 类目录下的方法级 canonical 路径。 ## 行为说明
**参数：** 这是平台桥接层最关键的接口。当前抽象直接暴露原始整型参数，而不是包装成统一事件对象，目的是让平台实现保留足够低层的解释空间。
- `hwnd` - 参数语义详见头文件声明。
- `msg` - 参数语义详见头文件声明。
- `wParam` - 参数语义详见头文件声明。
- `lParam` - 参数语义详见头文件声明。
**返回：** `void` - 无返回值。 在 Windows 路径中，这个方法会处理 `WM_KEYDOWN`、`WM_MOUSEMOVE`、`WM_CHAR` 等消息，然后调用 `InputManager::Process*`。
**示例：** ## 参数
```cpp - `hwnd` - 平台窗口句柄或等价标识。
#include <XCEngine/Input/InputModule.h> - `msg` - 平台消息类型。
- `wParam` - 平台消息参数 1。
- `lParam` - 平台消息参数 2。
void Example() { ## 返回值
XCEngine::Input::InputModule object;
// 根据上下文补齐参数后调用 InputModule::HandleMessage(...)。 - 无。
(void)object;
}
```
## 相关文档 ## 相关文档
- [返回类总览](InputModule.md) - [返回类型总览](InputModule.md)
- [返回模块目录](../Input.md) - [WindowsInputModule](../../Platform/Windows/WindowsInputModule/WindowsInputModule.md)

25
docs/api/XCEngine/Input/InputModule/Initialize.md
View File

@@ -1,31 +1,24 @@
# InputModule::Initialize # InputModule::Initialize
初始化内部状态。 初始化平台输入后端。
```cpp ```cpp
virtual void Initialize(void* windowHandle) = 0; virtual void Initialize(void* windowHandle) = 0;
``` ```
该方法声明于 `XCEngine/Input/InputModule.h`，当前页面用于固定 `InputModule` 类目录下的方法级 canonical 路径。 ## 行为说明
**参数：** 平台实现通常会在这里保存窗口句柄、建立必要状态，并准备接收平台消息。`InputModule` 本身不规定更具体的初始化流程。
- `windowHandle` - 参数语义详见头文件声明。
**返回：** `void` - 无返回值。 ## 参数
**示例：** - `windowHandle` - 平台窗口句柄或等价对象。
```cpp ## 返回值
#include <XCEngine/Input/InputModule.h>
void Example() { - 无。
XCEngine::Input::InputModule object;
// 根据上下文补齐参数后调用 InputModule::Initialize(...)。
(void)object;
}
```
## 相关文档 ## 相关文档
- [返回类总览](InputModule.md) - [返回类型总览](InputModule.md)
- [返回模块目录](../Input.md) - [Shutdown](Shutdown.md)

40
docs/api/XCEngine/Input/InputModule/InputModule.md
View File

@@ -6,29 +6,39 @@
**头文件**: `XCEngine/Input/InputModule.h` **头文件**: `XCEngine/Input/InputModule.h`
**描述**: 定义 `XCEngine/Input` 子目录中的 `InputModule` public API。 **描述**: 定义平台输入桥接层的最小接口，把操作系统消息翻译成 `InputManager` 可消费的调用。
## 概述 ## 概述
`InputModule.h` 是 `XCEngine/Input` 子目录 下的 public header，当前页面作为平行目录中的 canonical 总览，用于汇总该头文件暴露的主要声明。 `InputModule` 代表“输入后端适配器”这一层。它本身不保存全局输入状态，职责是从平台窗口系统接收原始消息，然后调用 `InputManager::Process*` 把这些消息转换成引擎内部统一格式。
## 声明概览 这层拆分的价值在于：
| 声明 | 类型 | 说明 | - 游戏代码只依赖 `InputManager`，不直接依赖 Win32、GLFW 或其它平台 API。
|------|------|------| - 各平台后端可以各自决定如何接收事件，但最后都汇总到同一套引擎输入状态。
| `InputModule` | `class` | 头文件中的公开声明。 |
## 公共方法 ## 当前实现中的位置
| 方法 | 描述 | - [WindowsInputModule](../../Platform/Windows/WindowsInputModule/WindowsInputModule.md) 是当前代码库里的实际实现。
- `InputModule` 本身只定义抽象接口，不提供默认逻辑。
## 线程语义
- 具体线程语义取决于平台后端。
- 当前 Windows 路径假定输入消息和 `InputManager` 更新都发生在窗口线程或主线程。
## 公开方法
| 方法 | 说明 |
|------|------| |------|------|
| [~InputModule()](Destructor.md) | 销毁对象并释放相关资源。 | | [Destructor](Destructor.md) | 虚析构函数。 |
| [Initialize](Initialize.md) | 初始化内部状态。 | | [Initialize](Initialize.md) | 初始化平台输入后端。 |
| [Shutdown](Shutdown.md) | 关闭并清理内部状态。 | | [Shutdown](Shutdown.md) | 关闭平台输入后端。 |
| [PumpEvents](PumpEvents.md) | 公开方法，详见头文件声明。 | | [PumpEvents](PumpEvents.md) | 主动轮询平台事件。 |
| [HandleMessage](HandleMessage.md) | 公开方法，详见头文件声明。 | | [HandleMessage](HandleMessage.md) | 处理一条平台消息。 |
## 相关文档 ## 相关文档
- [当前目录](../Input.md) - 返回 `Input` 平行目录 - [当前模块](../Input.md)
- [API 总索引](../../../main.md) - 返回顶层索引 - [WindowsInputModule](../../Platform/Windows/WindowsInputModule/WindowsInputModule.md)
- [Input Flow And Frame Semantics](../../../_guides/Input/Input-Flow-and-Frame-Semantics.md)

24
docs/api/XCEngine/Input/InputModule/PumpEvents.md
View File

@@ -1,30 +1,20 @@
# InputModule::PumpEvents # InputModule::PumpEvents
公开方法，详见头文件声明。 主动轮询平台事件。
```cpp ```cpp
virtual void PumpEvents() = 0; virtual void PumpEvents() = 0;
``` ```
该方法声明于 `XCEngine/Input/InputModule.h`，当前页面用于固定 `InputModule` 类目录下的方法级 canonical 路径。 ## 行为说明
**参数：** 无。 这个接口用于那些需要主动从平台消息队列拉取输入事件的后端。当前 Windows 实现提供了该方法，但方法体为空，因为现有路径主要通过外部窗口消息回调调用 `HandleMessage`。
**返回：** `void` - 无返回值。 ## 返回值
**示例：** - 无。
```cpp
#include <XCEngine/Input/InputModule.h>
void Example() {
XCEngine::Input::InputModule object;
// 根据上下文补齐参数后调用 InputModule::PumpEvents(...)。
(void)object;
}
```
## 相关文档 ## 相关文档
- [返回类总览](InputModule.md) - [返回类型总览](InputModule.md)
- [返回模块目录](../Input.md) - [HandleMessage](HandleMessage.md)

24
docs/api/XCEngine/Input/InputModule/Shutdown.md
View File

@@ -1,30 +1,20 @@
# InputModule::Shutdown # InputModule::Shutdown
关闭并清理内部状态。 关闭平台输入后端并释放相关状态。
```cpp ```cpp
virtual void Shutdown() = 0; virtual void Shutdown() = 0;
``` ```
该方法声明于 `XCEngine/Input/InputModule.h`，当前页面用于固定 `InputModule` 类目录下的方法级 canonical 路径。 ## 行为说明
**参数：** 无。 平台实现通常会在这里释放窗口句柄引用、内部缓存或平台输入资源。`InputModule` 不要求它必须同时调用 `InputManager::Shutdown`，这两层生命周期是否绑在一起由上层控制。
**返回：** `void` - 无返回值。 ## 返回值
**示例：** - 无。
```cpp
#include <XCEngine/Input/InputModule.h>
void Example() {
XCEngine::Input::InputModule object;
// 根据上下文补齐参数后调用 InputModule::Shutdown(...)。
(void)object;
}
```
## 相关文档 ## 相关文档
- [返回类总览](InputModule.md) - [返回类型总览](InputModule.md)
- [返回模块目录](../Input.md) - [Initialize](Initialize.md)

162
docs/api/XCEngine/Input/InputTypes/InputTypes.md
View File

@@ -6,106 +6,84 @@
**头文件**: `XCEngine/Input/InputTypes.h` **头文件**: `XCEngine/Input/InputTypes.h`
**描述**: 定义 `XCEngine/Input` 子目录中的 `InputTypes` public API。 **描述**: 定义键盘、鼠标和摇杆的基础枚举，用于输入查询、事件和映射配置。
## 概述 ## 概述
`InputTypes.h` 是 `XCEngine/Input` 子目录 下的 public header，当前页面作为平行目录中的 canonical 总览，用于汇总该头文件暴露的主要声明。 `InputTypes.h` 提供三组基础枚举：
## 声明概览 - `KeyCode`
- `MouseButton`
- `JoystickAxis`
| 声明 | 类型 | 说明 | 其中最重要的是 `KeyCode`。当前实现里，它不仅是“对外可见的按键名”，还会被 `InputManager` 直接转换为数组下标，因此它的底层数值会直接影响运行时行为。
## KeyCode
### 角色
- 用于 `IsKeyDown`、`GetAxis`、`RegisterButton` 等查询与配置接口。
- 被 Windows 输入桥接层用于把 Win32 `VK_*` 转换成引擎内部键值。
### 当前实现说明
- 这些值不是 Win32 `VK_*` 原值，也不应被当作平台原生键码直接持久化。
- 当前头文件中存在重复底层数值。
- `InputManager` 直接使用 `static_cast<size_t>(key)` 作为状态数组下标，因此这些重复值会造成状态别名。
### 已知重复值示例
| 底层值 | 重复项 |
|------|------|
| `40` | `Nine`、`Quote` |
| `51` | `Delete`、`Backspace` |
| `54` | `BracketRight`、`Comma` |
| `58` | `F1`、`LeftAlt` |
| `59` | `F2`、`LeftCtrl` |
| `60` | `F3`、`RightShift` |
| `61` | `F4`、`RightAlt` |
| `62` | `F5`、`RightCtrl` |
这意味着在当前版本中，某些键无法在状态层被完全区分。
### Windows 路径的额外限制
当前 `WindowsInputModule`：
- 把 `VK_SHIFT` 统一映射成 `LeftShift`
- 把 `VK_CONTROL` 统一映射成 `LeftCtrl`
- 把 `VK_MENU` 统一映射成 `LeftAlt`
因此即使 `KeyCode` 里定义了右侧修饰键，当前 Windows 路径也不会准确地产生这些值。
## MouseButton
| 值 | 底层值 | 说明 |
|------|------|------| |------|------|------|
| `KeyCode` | `enum class` | 头文件中的公开声明。 | | `Left` | `0` | 左键 |
| `MouseButton` | `enum class` | 头文件中的公开声明。 | | `Right` | `1` | 右键 |
| `JoystickAxis` | `enum class` | 头文件中的公开声明。 | | `Middle` | `2` | 中键 |
| `Button4` | `3` | 扩展键 4 |
| `Button5` | `4` | 扩展键 5 |
## 枚举值 `MouseButton` 当前数值唯一，并与 `InputManager` 的 5 槽鼠标按键状态数组对应。
| 枚举值 | 数值 | 描述 | ## JoystickAxis
|--------|------|------|
| `None` | `0` | 枚举项。 | | 值 | 底层值 | 说明 |
| `A` | `4` | 枚举项。 | |------|------|------|
| `B` | `5` | 枚举项。 | | `LeftX` | `0` | 左摇杆 X 轴 |
| `C` | `6` | 枚举项。 | | `LeftY` | `1` | 左摇杆 Y 轴 |
| `D` | `7` | 枚举项。 | | `RightX` | `2` | 右摇杆 X 轴 |
| `E` | `8` | 枚举项。 | | `RightY` | `3` | 右摇杆 Y 轴 |
| `F` | `9` | 枚举项。 | | `LeftTrigger` | `4` | 左扳机 |
| `G` | `10` | 枚举项。 | | `RightTrigger` | `5` | 右扳机 |
| `H` | `11` | 枚举项。 |
| `I` | `12` | 枚举项。 | 当前 `InputManager` 还没有对应的摇杆状态存储与更新逻辑，因此这些枚举更多是为未来扩展预留。
| `J` | `13` | 枚举项。 |
| `K` | `14` | 枚举项。 |
| `L` | `15` | 枚举项。 |
| `M` | `16` | 枚举项。 |
| `N` | `17` | 枚举项。 |
| `O` | `18` | 枚举项。 |
| `P` | `19` | 枚举项。 |
| `Q` | `20` | 枚举项。 |
| `R` | `21` | 枚举项。 |
| `S` | `22` | 枚举项。 |
| `T` | `23` | 枚举项。 |
| `U` | `24` | 枚举项。 |
| `V` | `25` | 枚举项。 |
| `W` | `26` | 枚举项。 |
| `X` | `27` | 枚举项。 |
| `Y` | `28` | 枚举项。 |
| `Z` | `29` | 枚举项。 |
| `F1` | `58` | 枚举项。 |
| `F2` | `59` | 枚举项。 |
| `F3` | `60` | 枚举项。 |
| `F4` | `61` | 枚举项。 |
| `F5` | `62` | 枚举项。 |
| `F6` | `63` | 枚举项。 |
| `F7` | `64` | 枚举项。 |
| `F8` | `65` | 枚举项。 |
| `F9` | `66` | 枚举项。 |
| `F10` | `67` | 枚举项。 |
| `F11` | `68` | 枚举项。 |
| `F12` | `69` | 枚举项。 |
| `Space` | `49` | 枚举项。 |
| `Tab` | `48` | 枚举项。 |
| `Enter` | `36` | 枚举项。 |
| `Escape` | `53` | 枚举项。 |
| `LeftShift` | `56` | 枚举项。 |
| `RightShift` | `60` | 枚举项。 |
| `LeftCtrl` | `59` | 枚举项。 |
| `RightCtrl` | `62` | 枚举项。 |
| `LeftAlt` | `58` | 枚举项。 |
| `RightAlt` | `61` | 枚举项。 |
| `Up` | `126` | 枚举项。 |
| `Down` | `125` | 枚举项。 |
| `Left` | `123` | 枚举项。 |
| `Right` | `124` | 枚举项。 |
| `Home` | `115` | 枚举项。 |
| `End` | `119` | 枚举项。 |
| `PageUp` | `116` | 枚举项。 |
| `PageDown` | `121` | 枚举项。 |
| `Delete` | `51` | 枚举项。 |
| `Backspace` | `51` | 枚举项。 |
| `Zero` | `39` | 枚举项。 |
| `One` | `30` | 枚举项。 |
| `Two` | `31` | 枚举项。 |
| `Three` | `32` | 枚举项。 |
| `Four` | `33` | 枚举项。 |
| `Five` | `34` | 枚举项。 |
| `Six` | `35` | 枚举项。 |
| `Seven` | `37` | 枚举项。 |
| `Eight` | `38` | 枚举项。 |
| `Nine` | `40` | 枚举项。 |
| `Minus` | `43` | 枚举项。 |
| `Equals` | `46` | 枚举项。 |
| `BracketLeft` | `47` | 枚举项。 |
| `BracketRight` | `54` | 枚举项。 |
| `Semicolon` | `42` | 枚举项。 |
| `Quote` | `40` | 枚举项。 |
| `Comma` | `54` | 枚举项。 |
| `Period` | `55` | 枚举项。 |
| `Slash` | `44` | 枚举项。 |
| `Backslash` | `45` | 枚举项。 |
| `Backtick` | `41` | 枚举项。 |
## 相关文档 ## 相关文档
- [当前目录](../Input.md) - 返回 `Input` 平行目录 - [当前模块](../Input.md)
- [API 总索引](../../../main.md) - 返回顶层索引 - [InputManager](../InputManager/InputManager.md)
- [InputEvent](../InputEvent/InputEvent.md)
- [Input Flow And Frame Semantics](../../../_guides/Input/Input-Flow-and-Frame-Semantics.md)

115
docs/api/_guides/Input/Input-Flow-and-Frame-Semantics.md Normal file
View File

@@ -0,0 +1,115 @@
# Input Flow And Frame Semantics
## 这套输入系统怎么理解
当前 XCEngine 输入系统更接近“轻量级、同步、帧驱动的输入管理器”，而不是完整设备抽象框架。
它有两个核心层：
- `InputModule` 负责接平台消息。
- `InputManager` 负责保存状态并提供事件与查询接口。
这意味着真正的输入流向是：
1. 平台窗口系统产生命令或消息。
2. 平台后端把消息翻译成 `ProcessKeyDown`、`ProcessMouseMove` 一类调用。
3. `InputManager` 更新状态并同步广播事件。
4. 游戏或工具层在当前帧读取轮询状态。
5. `Update()` 在帧边界清理瞬时状态。
## 为什么同时保留事件和轮询
事件和轮询各有适合的地方：
- UI、输入法、编辑器面板更适合订阅事件。
- 游戏逻辑、相机控制、角色移动更适合每帧轮询。
`InputManager` 同时提供这两种方式，是为了避免你在上层自己重复维护一套输入缓存。
## 帧边界怎么理解
当前实现里，`Update()` 不是“采集输入”，而是“结束上一帧的瞬时状态”。
它会清理：
- `IsKeyPressed` 依赖的本帧按下标记
- `IsMouseButtonClicked` 依赖的本帧点击标记
- `GetMouseDelta`
- `GetMouseScrollDelta`
所以最重要的实践是：
- 每帧只调用一次 `Update()`。
- 保持调用时机一致。
- 在清理之前，先消费掉当前帧的瞬时输入。
## 和 Unity 的对照
从使用方式上看，`InputManager` 很像 Unity 旧版 Input Manager：
- 有具名轴：`Horizontal`、`Vertical`
- 有具名按钮：`Jump`、`Fire1`、`Fire2`、`Fire3`
- 查询接口偏向 `GetAxis` / `GetButton`
但当前实现并不等同于 Unity：
- 没有平滑、重力、灵敏度、死区等高级参数。
- `GetAxisRaw` 当前只在“按下这一帧”返回非零，不等同于 Unity 中“原始持续值”的语义。
- `Mouse X` 和 `Mouse Y` 默认虽然被注册了，但当前实现并不会通过鼠标移动更新它们。
## 平台桥接是怎么接进来的
`InputModule` 的意义是把平台消息层隔离掉。当前 Windows 路径里：
- `WindowsInputModule::HandleMessage` 负责处理 `WM_KEYDOWN`、`WM_MOUSEMOVE`、`WM_MOUSEWHEEL` 等消息。
- 它再调用 `InputManager::Process*` 统一更新状态。
这样做的好处是：
- 游戏层不用知道 Win32 消息细节。
- 将来如果换 GLFW、SDL 或其它平台层，`InputManager` 可以不变。
## 当前版本最该知道的限制
- `KeyCode` 底层值当前有重复，部分键会共享状态槽。
- Windows 路径当前不能准确区分左右 Ctrl / Alt / Shift。
- 触摸与摇杆接口基本是预留位。
- 事件回调是同步执行的，不是异步消息队列。
- `Shutdown()` 当前不会清空事件监听器；如果单例跨生命周期反复初始化，要自己管理订阅者。
## 推荐使用方式
初始化阶段：
```cpp
using namespace XCEngine::Input;
InputManager::Get().Initialize(windowHandle);
```
平台消息阶段：
```cpp
windowsInputModule.HandleMessage(hwnd, msg, wParam, lParam);
```
游戏逻辑阶段：
```cpp
if (InputManager::Get().GetButton("Jump")) {
// ...
}
```
帧边界阶段：
```cpp
InputManager::Get().Update(deltaTime);
```
## 相关 API
- [Input](../../XCEngine/Input/Input.md)
- [InputManager](../../XCEngine/Input/InputManager/InputManager.md)
- [InputModule](../../XCEngine/Input/InputModule/InputModule.md)
- [InputTypes](../../XCEngine/Input/InputTypes/InputTypes.md)

4
docs/api/_meta/rebuild-status.md
View File

@@ -1,12 +1,12 @@
# API 文档重构状态 # API 文档重构状态
**生成时间**: `2026-03-26 17:25:36` **生成时间**: `2026-03-26 17:39:11`
**来源**: `docs/api/_tools/audit_api_docs.py` **来源**: `docs/api/_tools/audit_api_docs.py`
## 摘要 ## 摘要
- Markdown 页面数（全部）: `2442` - Markdown 页面数（全部）: `2443`
- Markdown 页面数（canonical）: `2436` - Markdown 页面数（canonical）: `2436`
- Public headers 数: `185` - Public headers 数: `185`
- 有效头文件引用数（全部）: `185` - 有效头文件引用数（全部）: `185`