docs: rebuild Input API content
This commit is contained in:
@@ -4,19 +4,50 @@
|
||||
|
||||
**类型**: `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`
|
||||
- [InputEvent](InputEvent/InputEvent.md) - `InputEvent.h`
|
||||
- [InputManager](InputManager/InputManager.md) - `InputManager.h`
|
||||
- [InputModule](InputModule/InputModule.md) - `InputModule.h`
|
||||
- [InputTypes](InputTypes/InputTypes.md) - `InputTypes.h`
|
||||
- [InputAxis](InputAxis/InputAxis.md) - `InputAxis.h`，逻辑轴配置对象。
|
||||
- [InputEvent](InputEvent/InputEvent.md) - `InputEvent.h`，输入事件结构体定义。
|
||||
- [InputManager](InputManager/InputManager.md) - `InputManager.h`，全局输入状态与事件中心。
|
||||
- [InputModule](InputModule/InputModule.md) - `InputModule.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 平台当前的具体输入桥接实现。
|
||||
|
||||
## 相关文档
|
||||
|
||||
|
||||
@@ -1,43 +1,39 @@
|
||||
# InputAxis::InputAxis()
|
||||
# InputAxis::Constructor
|
||||
|
||||
构造对象。
|
||||
|
||||
该方法在 `XCEngine/Input/InputAxis.h` 中提供了 2 个重载，当前页面统一汇总这些公开声明。
|
||||
|
||||
## 重载 1: 声明
|
||||
构造一个逻辑轴配置对象。
|
||||
|
||||
```cpp
|
||||
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
|
||||
InputAxis(const Containers::String& name, KeyCode positive, KeyCode negative = KeyCode::None) : m_name(name), m_positiveKey(positive), m_negativeKey(negative);
|
||||
```
|
||||
|
||||
**参数：**
|
||||
- `name` - 参数语义详见头文件声明。
|
||||
- `positive` - 参数语义详见头文件声明。
|
||||
- `negative` - 参数语义详见头文件声明。
|
||||
|
||||
**返回：** `void` - 无返回值。
|
||||
|
||||
**示例：**
|
||||
|
||||
```cpp
|
||||
#include <XCEngine/Input/InputAxis.h>
|
||||
|
||||
void Example() {
|
||||
XCEngine::Input::InputAxis object;
|
||||
}
|
||||
XCEngine::Input::InputAxis axis("Horizontal", XCEngine::Input::KeyCode::D, XCEngine::Input::KeyCode::A);
|
||||
```
|
||||
|
||||
## 相关文档
|
||||
|
||||
- [返回类总览](InputAxis.md)
|
||||
- [返回模块目录](../Input.md)
|
||||
- [返回类型总览](InputAxis.md)
|
||||
- [SetKeys](SetKeys.md)
|
||||
|
||||
@@ -1,30 +1,26 @@
|
||||
# InputAxis::GetName
|
||||
|
||||
获取相关状态或对象。
|
||||
读取轴名。
|
||||
|
||||
```cpp
|
||||
const Containers::String& GetName() const;
|
||||
```
|
||||
|
||||
该方法声明于 `XCEngine/Input/InputAxis.h`，当前页面用于固定 `InputAxis` 类目录下的方法级 canonical 路径。
|
||||
## 行为说明
|
||||
|
||||
**参数：** 无。
|
||||
返回内部保存的名称引用，不做复制、不做标准化，也不会检查唯一性。`InputManager::RegisterAxis` 会用这个名称作为映射键。
|
||||
|
||||
**返回：** `const Containers::String&` - 返回值语义详见头文件声明。
|
||||
## 返回值
|
||||
|
||||
**示例：**
|
||||
- `const Containers::String&` - 当前轴名。
|
||||
|
||||
## 示例
|
||||
|
||||
```cpp
|
||||
#include <XCEngine/Input/InputAxis.h>
|
||||
|
||||
void Example() {
|
||||
XCEngine::Input::InputAxis object;
|
||||
// 根据上下文补齐参数后调用 InputAxis::GetName(...)。
|
||||
(void)object;
|
||||
}
|
||||
XCEngine::Input::InputAxis axis("Vertical", XCEngine::Input::KeyCode::W, XCEngine::Input::KeyCode::S);
|
||||
auto& name = axis.GetName();
|
||||
```
|
||||
|
||||
## 相关文档
|
||||
|
||||
- [返回类总览](InputAxis.md)
|
||||
- [返回模块目录](../Input.md)
|
||||
- [返回类型总览](InputAxis.md)
|
||||
|
||||
@@ -1,30 +1,26 @@
|
||||
# InputAxis::GetNegativeKey
|
||||
|
||||
获取相关状态或对象。
|
||||
读取轴的负方向按键。
|
||||
|
||||
```cpp
|
||||
KeyCode GetNegativeKey() const;
|
||||
```
|
||||
|
||||
该方法声明于 `XCEngine/Input/InputAxis.h`，当前页面用于固定 `InputAxis` 类目录下的方法级 canonical 路径。
|
||||
## 行为说明
|
||||
|
||||
**参数：** 无。
|
||||
当前返回内部保存的 `m_negativeKey`。如果返回 `KeyCode::None`，表示该轴当前没有配置负方向键。
|
||||
|
||||
**返回：** `KeyCode` - 返回值语义详见头文件声明。
|
||||
## 返回值
|
||||
|
||||
**示例：**
|
||||
- `KeyCode` - 负方向按键。
|
||||
|
||||
## 示例
|
||||
|
||||
```cpp
|
||||
#include <XCEngine/Input/InputAxis.h>
|
||||
|
||||
void Example() {
|
||||
XCEngine::Input::InputAxis object;
|
||||
// 根据上下文补齐参数后调用 InputAxis::GetNegativeKey(...)。
|
||||
(void)object;
|
||||
}
|
||||
XCEngine::Input::KeyCode negative = axis.GetNegativeKey();
|
||||
```
|
||||
|
||||
## 相关文档
|
||||
|
||||
- [返回类总览](InputAxis.md)
|
||||
- [返回模块目录](../Input.md)
|
||||
- [返回类型总览](InputAxis.md)
|
||||
- [GetPositiveKey](GetPositiveKey.md)
|
||||
|
||||
@@ -1,30 +1,26 @@
|
||||
# InputAxis::GetPositiveKey
|
||||
|
||||
获取相关状态或对象。
|
||||
读取轴的正方向按键。
|
||||
|
||||
```cpp
|
||||
KeyCode GetPositiveKey() const;
|
||||
```
|
||||
|
||||
该方法声明于 `XCEngine/Input/InputAxis.h`，当前页面用于固定 `InputAxis` 类目录下的方法级 canonical 路径。
|
||||
## 行为说明
|
||||
|
||||
**参数：** 无。
|
||||
当前返回内部保存的 `m_positiveKey`。如果返回 `KeyCode::None`，表示该轴当前没有配置正方向键。
|
||||
|
||||
**返回：** `KeyCode` - 返回值语义详见头文件声明。
|
||||
## 返回值
|
||||
|
||||
**示例：**
|
||||
- `KeyCode` - 正方向按键。
|
||||
|
||||
## 示例
|
||||
|
||||
```cpp
|
||||
#include <XCEngine/Input/InputAxis.h>
|
||||
|
||||
void Example() {
|
||||
XCEngine::Input::InputAxis object;
|
||||
// 根据上下文补齐参数后调用 InputAxis::GetPositiveKey(...)。
|
||||
(void)object;
|
||||
}
|
||||
XCEngine::Input::KeyCode positive = axis.GetPositiveKey();
|
||||
```
|
||||
|
||||
## 相关文档
|
||||
|
||||
- [返回类总览](InputAxis.md)
|
||||
- [返回模块目录](../Input.md)
|
||||
- [返回类型总览](InputAxis.md)
|
||||
- [GetNegativeKey](GetNegativeKey.md)
|
||||
|
||||
@@ -1,30 +1,31 @@
|
||||
# InputAxis::GetValue
|
||||
|
||||
获取相关状态或对象。
|
||||
读取 `InputAxis` 对象内部保存的数值。
|
||||
|
||||
```cpp
|
||||
float GetValue() const;
|
||||
```
|
||||
|
||||
该方法声明于 `XCEngine/Input/InputAxis.h`，当前页面用于固定 `InputAxis` 类目录下的方法级 canonical 路径。
|
||||
## 行为说明
|
||||
|
||||
**参数：** 无。
|
||||
这个值只是 `InputAxis` 对象自己的成员 `m_value`。当前 `InputManager::GetAxis` 和 `GetAxisRaw` 不会读取它，而是根据按键状态重新计算轴值。
|
||||
|
||||
**返回：** `float` - 返回值语义详见头文件声明。
|
||||
因此，它更像是一个通用配置/缓存字段，而不是 `InputManager` 的真实运行时输出。
|
||||
|
||||
**示例：**
|
||||
## 返回值
|
||||
|
||||
- `float` - 当前对象内部保存的数值。
|
||||
|
||||
## 示例
|
||||
|
||||
```cpp
|
||||
#include <XCEngine/Input/InputAxis.h>
|
||||
|
||||
void Example() {
|
||||
XCEngine::Input::InputAxis object;
|
||||
// 根据上下文补齐参数后调用 InputAxis::GetValue(...)。
|
||||
(void)object;
|
||||
}
|
||||
XCEngine::Input::InputAxis axis;
|
||||
axis.SetValue(0.5f);
|
||||
float value = axis.GetValue();
|
||||
```
|
||||
|
||||
## 相关文档
|
||||
|
||||
- [返回类总览](InputAxis.md)
|
||||
- [返回模块目录](../Input.md)
|
||||
- [返回类型总览](InputAxis.md)
|
||||
- [SetValue](SetValue.md)
|
||||
- [InputManager::GetAxis](../InputManager/GetAxis.md)
|
||||
|
||||
@@ -6,31 +6,43 @@
|
||||
|
||||
**头文件**: `XCEngine/Input/InputAxis.h`
|
||||
|
||||
**描述**: 定义 `XCEngine/Input` 子目录中的 `InputAxis` public API。
|
||||
**描述**: 描述一个具名逻辑轴及其正负方向按键映射。
|
||||
|
||||
## 概述
|
||||
|
||||
`InputAxis.h` 是 `XCEngine/Input` 子目录 下的 public header，当前页面作为平行目录中的 canonical 总览，用于汇总该头文件暴露的主要声明。
|
||||
`InputAxis` 是 `InputManager` 的配置对象，而不是完整的运行时输入通道。它保存三类信息：
|
||||
|
||||
## 声明概览
|
||||
- 轴名
|
||||
- 正方向按键
|
||||
- 负方向按键
|
||||
|
||||
| 声明 | 类型 | 说明 |
|
||||
|------|------|------|
|
||||
| `InputAxis` | `class` | 头文件中的公开声明。 |
|
||||
此外它还有一个独立的 `m_value` 字段，但要特别注意：当前 `InputManager::GetAxis` 和 `GetAxisRaw` 都不会读取这个值，而是每次根据按键状态重新计算结果。
|
||||
|
||||
## 公共方法
|
||||
## 当前实现中的角色
|
||||
|
||||
| 方法 | 描述 |
|
||||
- 在 `InputManager::Initialize` 时，用它注册默认的 `Horizontal`、`Vertical`、`Mouse X` 和 `Mouse Y` 逻辑轴。
|
||||
- 在运行时，可通过 [RegisterAxis](../InputManager/RegisterAxis.md) 注册自定义具名轴。
|
||||
- 当前只支持“两键一轴”模型，不支持平滑曲线、死区、灵敏度或设备组合。
|
||||
|
||||
## 生命周期
|
||||
|
||||
- [Constructor](Constructor.md) 支持默认构造和具名按键构造。
|
||||
- `InputAxis` 是值类型，通常按值传给 `InputManager`。
|
||||
|
||||
## 公开方法
|
||||
|
||||
| 方法 | 说明 |
|
||||
|------|------|
|
||||
| [InputAxis()](Constructor.md) | 构造对象。 |
|
||||
| [GetName](GetName.md) | 获取相关状态或对象。 |
|
||||
| [GetPositiveKey](GetPositiveKey.md) | 获取相关状态或对象。 |
|
||||
| [GetNegativeKey](GetNegativeKey.md) | 获取相关状态或对象。 |
|
||||
| [SetKeys](SetKeys.md) | 设置相关状态或配置。 |
|
||||
| [GetValue](GetValue.md) | 获取相关状态或对象。 |
|
||||
| [SetValue](SetValue.md) | 设置相关状态或配置。 |
|
||||
| [Constructor](Constructor.md) | 构造一个轴配置对象。 |
|
||||
| [GetName](GetName.md) | 读取轴名。 |
|
||||
| [GetPositiveKey](GetPositiveKey.md) | 读取正方向按键。 |
|
||||
| [GetNegativeKey](GetNegativeKey.md) | 读取负方向按键。 |
|
||||
| [SetKeys](SetKeys.md) | 修改正负方向按键。 |
|
||||
| [GetValue](GetValue.md) | 读取对象自身保存的值。 |
|
||||
| [SetValue](SetValue.md) | 写入对象自身保存的值。 |
|
||||
|
||||
## 相关文档
|
||||
|
||||
- [当前目录](../Input.md) - 返回 `Input` 平行目录
|
||||
- [API 总索引](../../../main.md) - 返回顶层索引
|
||||
- [当前模块](../Input.md)
|
||||
- [InputManager](../InputManager/InputManager.md)
|
||||
- [Input Flow And Frame Semantics](../../../_guides/Input/Input-Flow-and-Frame-Semantics.md)
|
||||
|
||||
@@ -1,32 +1,31 @@
|
||||
# InputAxis::SetKeys
|
||||
|
||||
设置相关状态或配置。
|
||||
修改轴的正负方向按键。
|
||||
|
||||
```cpp
|
||||
void SetKeys(KeyCode positive, KeyCode negative);
|
||||
```
|
||||
|
||||
该方法声明于 `XCEngine/Input/InputAxis.h`，当前页面用于固定 `InputAxis` 类目录下的方法级 canonical 路径。
|
||||
## 行为说明
|
||||
|
||||
**参数：**
|
||||
- `positive` - 参数语义详见头文件声明。
|
||||
- `negative` - 参数语义详见头文件声明。
|
||||
当前实现仅更新内部两个键值字段，不做合法性检查，也不会通知 `InputManager`。如果这个对象已经按值注册进 `InputManager`，后续再修改原对象不会影响 `InputManager` 内部保存的副本。
|
||||
|
||||
**返回：** `void` - 无返回值。
|
||||
## 参数
|
||||
|
||||
**示例：**
|
||||
- `positive` - 新的正方向按键。
|
||||
- `negative` - 新的负方向按键。
|
||||
|
||||
## 返回值
|
||||
|
||||
- 无。
|
||||
|
||||
## 示例
|
||||
|
||||
```cpp
|
||||
#include <XCEngine/Input/InputAxis.h>
|
||||
|
||||
void Example() {
|
||||
XCEngine::Input::InputAxis object;
|
||||
// 根据上下文补齐参数后调用 InputAxis::SetKeys(...)。
|
||||
(void)object;
|
||||
}
|
||||
axis.SetKeys(XCEngine::Input::KeyCode::Right, XCEngine::Input::KeyCode::Left);
|
||||
```
|
||||
|
||||
## 相关文档
|
||||
|
||||
- [返回类总览](InputAxis.md)
|
||||
- [返回模块目录](../Input.md)
|
||||
- [返回类型总览](InputAxis.md)
|
||||
- [Constructor](Constructor.md)
|
||||
|
||||
@@ -1,31 +1,31 @@
|
||||
# InputAxis::SetValue
|
||||
|
||||
设置相关状态或配置。
|
||||
写入 `InputAxis` 对象内部保存的数值。
|
||||
|
||||
```cpp
|
||||
void SetValue(float value);
|
||||
```
|
||||
|
||||
该方法声明于 `XCEngine/Input/InputAxis.h`，当前页面用于固定 `InputAxis` 类目录下的方法级 canonical 路径。
|
||||
## 行为说明
|
||||
|
||||
**参数：**
|
||||
- `value` - 参数语义详见头文件声明。
|
||||
当前实现只更新 `m_value`。这不会改变 `InputManager::GetAxis` 或 `GetAxisRaw` 的返回结果，因为管理器当前并不读取该字段。
|
||||
|
||||
**返回：** `void` - 无返回值。
|
||||
## 参数
|
||||
|
||||
**示例：**
|
||||
- `value` - 要保存的值。
|
||||
|
||||
## 返回值
|
||||
|
||||
- 无。
|
||||
|
||||
## 示例
|
||||
|
||||
```cpp
|
||||
#include <XCEngine/Input/InputAxis.h>
|
||||
|
||||
void Example() {
|
||||
XCEngine::Input::InputAxis object;
|
||||
// 根据上下文补齐参数后调用 InputAxis::SetValue(...)。
|
||||
(void)object;
|
||||
}
|
||||
XCEngine::Input::InputAxis axis;
|
||||
axis.SetValue(1.0f);
|
||||
```
|
||||
|
||||
## 相关文档
|
||||
|
||||
- [返回类总览](InputAxis.md)
|
||||
- [返回模块目录](../Input.md)
|
||||
- [返回类型总览](InputAxis.md)
|
||||
- [GetValue](GetValue.md)
|
||||
|
||||
@@ -6,34 +6,73 @@
|
||||
|
||||
**头文件**: `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` | 头文件中的公开声明。 |
|
||||
| `MouseButtonEvent` | `struct` | 头文件中的公开声明。 |
|
||||
| `MouseMoveEvent` | `struct` | 头文件中的公开声明。 |
|
||||
| `MouseWheelEvent` | `struct` | 头文件中的公开声明。 |
|
||||
| `TextInputEvent` | `struct` | 头文件中的公开声明。 |
|
||||
| `TouchState` | `struct` | 头文件中的公开声明。 |
|
||||
| `keyCode` | `KeyCode` | 键值。 |
|
||||
| `alt` | `bool` | 事件发生时是否按下 Alt。 |
|
||||
| `ctrl` | `bool` | 事件发生时是否按下 Ctrl。 |
|
||||
| `shift` | `bool` | 事件发生时是否按下 Shift。 |
|
||||
| `meta` | `bool` | 事件发生时是否按下 Meta。当前 Windows 路径始终为 `false`。 |
|
||||
| `type` | `KeyEvent::Type` | `Down`、`Up` 或 `Repeat`。 |
|
||||
|
||||
## 结构体成员
|
||||
### `MouseButtonEvent`
|
||||
|
||||
| 成员 | 类型 | 描述 | 默认值 |
|
||||
|------|------|------|--------|
|
||||
| `keyCode` | `KeyCode` | 结构体公开字段。 | - |
|
||||
| `alt` | `bool` | 结构体公开字段。 | - |
|
||||
| `ctrl` | `bool` | 结构体公开字段。 | - |
|
||||
| `shift` | `bool` | 结构体公开字段。 | - |
|
||||
| `meta` | `bool` | 结构体公开字段。 | - |
|
||||
| 字段 | 类型 | 说明 |
|
||||
|------|------|------|
|
||||
| `button` | `MouseButton` | 鼠标按键。 |
|
||||
| `position` | `Math::Vector2` | 事件位置。 |
|
||||
| `type` | `MouseButtonEvent::Type` | `Pressed` 或 `Released`。 |
|
||||
|
||||
### `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` 平行目录
|
||||
- [API 总索引](../../../main.md) - 返回顶层索引
|
||||
- [当前模块](../Input.md)
|
||||
- [InputManager](../InputManager/InputManager.md)
|
||||
- [Input Flow And Frame Semantics](../../../_guides/Input/Input-Flow-and-Frame-Semantics.md)
|
||||
|
||||
@@ -1,30 +1,33 @@
|
||||
# InputManager::ClearAxes
|
||||
|
||||
清空内部数据。
|
||||
清空当前所有逻辑轴和逻辑按钮映射。
|
||||
|
||||
```cpp
|
||||
void ClearAxes();
|
||||
```
|
||||
|
||||
该方法声明于 `XCEngine/Input/InputManager.h`，当前页面用于固定 `InputManager` 类目录下的方法级 canonical 路径。
|
||||
## 行为说明
|
||||
|
||||
**参数：** 无。
|
||||
尽管名字叫 `ClearAxes`，当前实现会同时执行：
|
||||
|
||||
**返回：** `void` - 无返回值。
|
||||
- `m_axes.clear()`
|
||||
- `m_buttons.clear()`
|
||||
|
||||
**示例：**
|
||||
它不会清空键盘、鼠标或事件监听状态。
|
||||
|
||||
## 返回值
|
||||
|
||||
- 无。
|
||||
|
||||
## 示例
|
||||
|
||||
```cpp
|
||||
#include <XCEngine/Input/InputManager.h>
|
||||
|
||||
void Example() {
|
||||
XCEngine::Input::InputManager object;
|
||||
// 根据上下文补齐参数后调用 InputManager::ClearAxes(...)。
|
||||
(void)object;
|
||||
}
|
||||
auto& input = XCEngine::Input::InputManager::Get();
|
||||
input.ClearAxes();
|
||||
```
|
||||
|
||||
## 相关文档
|
||||
|
||||
- [返回类总览](InputManager.md)
|
||||
- [返回模块目录](../Input.md)
|
||||
- [返回类型总览](InputManager.md)
|
||||
- [RegisterAxis](RegisterAxis.md)
|
||||
- [RegisterButton](RegisterButton.md)
|
||||
|
||||
@@ -1,29 +1,26 @@
|
||||
# InputManager::Get
|
||||
|
||||
获取相关状态或对象。
|
||||
获取进程级全局 `InputManager` 实例。
|
||||
|
||||
```cpp
|
||||
static InputManager& Get();
|
||||
```
|
||||
|
||||
该方法声明于 `XCEngine/Input/InputManager.h`，当前页面用于固定 `InputManager` 类目录下的方法级 canonical 路径。
|
||||
## 行为说明
|
||||
|
||||
**参数：** 无。
|
||||
当前实现使用函数内静态对象保存单例。`Get()` 本身不会初始化状态数组，也不会注册默认映射；这些工作要由 [Initialize](Initialize.md) 完成。
|
||||
|
||||
**返回：** `InputManager&` - 返回值语义详见头文件声明。
|
||||
## 返回值
|
||||
|
||||
**示例：**
|
||||
- `InputManager&` - 全局输入管理器引用。
|
||||
|
||||
## 示例
|
||||
|
||||
```cpp
|
||||
#include <XCEngine/Input/InputManager.h>
|
||||
|
||||
void Example() {
|
||||
auto& instance = XCEngine::Input::InputManager::Get();
|
||||
(void)instance;
|
||||
}
|
||||
XCEngine::Input::InputManager& input = XCEngine::Input::InputManager::Get();
|
||||
```
|
||||
|
||||
## 相关文档
|
||||
|
||||
- [返回类总览](InputManager.md)
|
||||
- [返回模块目录](../Input.md)
|
||||
- [返回类型总览](InputManager.md)
|
||||
- [Initialize](Initialize.md)
|
||||
|
||||
@@ -1,31 +1,43 @@
|
||||
# InputManager::GetAxis
|
||||
|
||||
获取相关状态或对象。
|
||||
读取一个具名逻辑轴的当前值。
|
||||
|
||||
```cpp
|
||||
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
|
||||
#include <XCEngine/Input/InputManager.h>
|
||||
|
||||
void Example() {
|
||||
XCEngine::Input::InputManager object;
|
||||
// 根据上下文补齐参数后调用 InputManager::GetAxis(...)。
|
||||
(void)object;
|
||||
}
|
||||
float horizontal = XCEngine::Input::InputManager::Get().GetAxis("Horizontal");
|
||||
```
|
||||
|
||||
## 相关文档
|
||||
|
||||
- [返回类总览](InputManager.md)
|
||||
- [返回模块目录](../Input.md)
|
||||
- [返回类型总览](InputManager.md)
|
||||
- [GetAxisRaw](GetAxisRaw.md)
|
||||
- [RegisterAxis](RegisterAxis.md)
|
||||
|
||||
@@ -1,31 +1,35 @@
|
||||
# InputManager::GetAxisRaw
|
||||
|
||||
获取相关状态或对象。
|
||||
读取一个具名逻辑轴的当前原始值。
|
||||
|
||||
```cpp
|
||||
float GetAxisRaw(const Containers::String& axisName) const;
|
||||
```
|
||||
|
||||
该方法声明于 `XCEngine/Input/InputManager.h`，当前页面用于固定 `InputManager` 类目录下的方法级 canonical 路径。
|
||||
## 行为说明
|
||||
|
||||
**参数：**
|
||||
- `axisName` - 参数语义详见头文件声明。
|
||||
当前实现与 [GetAxis](GetAxis.md) 最大的区别在于，它检查的是 `IsKeyPressed()`，而不是 `IsKeyDown()`。这意味着：
|
||||
|
||||
**返回：** `float` - 返回值语义详见头文件声明。
|
||||
- 只有在按键“刚按下的那一帧”才会返回 `1.0f` 或 `-1.0f`
|
||||
- 按住不放跨帧后，结果会回到 `0.0f`
|
||||
|
||||
**示例：**
|
||||
这和很多引擎里“raw axis 仍然表示持续按住的未平滑值”的直觉不同，因此需要特别小心。
|
||||
|
||||
## 参数
|
||||
|
||||
- `axisName` - 逻辑轴名称。
|
||||
|
||||
## 返回值
|
||||
|
||||
- `float` - 当前帧的原始边沿值。
|
||||
|
||||
## 示例
|
||||
|
||||
```cpp
|
||||
#include <XCEngine/Input/InputManager.h>
|
||||
|
||||
void Example() {
|
||||
XCEngine::Input::InputManager object;
|
||||
// 根据上下文补齐参数后调用 InputManager::GetAxisRaw(...)。
|
||||
(void)object;
|
||||
}
|
||||
float raw = XCEngine::Input::InputManager::Get().GetAxisRaw("Horizontal");
|
||||
```
|
||||
|
||||
## 相关文档
|
||||
|
||||
- [返回类总览](InputManager.md)
|
||||
- [返回模块目录](../Input.md)
|
||||
- [返回类型总览](InputManager.md)
|
||||
- [GetAxis](GetAxis.md)
|
||||
|
||||
@@ -1,31 +1,37 @@
|
||||
# InputManager::GetButton
|
||||
|
||||
获取相关状态或对象。
|
||||
查询一个具名逻辑按钮当前是否按下。
|
||||
|
||||
```cpp
|
||||
bool GetButton(const Containers::String& buttonName) const;
|
||||
```
|
||||
|
||||
该方法声明于 `XCEngine/Input/InputManager.h`，当前页面用于固定 `InputManager` 类目录下的方法级 canonical 路径。
|
||||
## 行为说明
|
||||
|
||||
**参数：**
|
||||
- `buttonName` - 参数语义详见头文件声明。
|
||||
当前逻辑按钮只是“名字到 `KeyCode`”的映射。这个方法会：
|
||||
|
||||
**返回：** `bool` - 返回值语义详见头文件声明。
|
||||
1. 查找 `buttonName`
|
||||
2. 如果找到，则调用 `IsKeyDown(mappedKey)`
|
||||
3. 如果没找到，则返回 `false`
|
||||
|
||||
**示例：**
|
||||
## 参数
|
||||
|
||||
- `buttonName` - 逻辑按钮名称。
|
||||
|
||||
## 返回值
|
||||
|
||||
- `bool` - 当前是否按下。
|
||||
|
||||
## 示例
|
||||
|
||||
```cpp
|
||||
#include <XCEngine/Input/InputManager.h>
|
||||
|
||||
void Example() {
|
||||
XCEngine::Input::InputManager object;
|
||||
// 根据上下文补齐参数后调用 InputManager::GetButton(...)。
|
||||
(void)object;
|
||||
if (XCEngine::Input::InputManager::Get().GetButton("Jump")) {
|
||||
// ...
|
||||
}
|
||||
```
|
||||
|
||||
## 相关文档
|
||||
|
||||
- [返回类总览](InputManager.md)
|
||||
- [返回模块目录](../Input.md)
|
||||
- [返回类型总览](InputManager.md)
|
||||
- [GetButtonDown](GetButtonDown.md)
|
||||
- [RegisterButton](RegisterButton.md)
|
||||
|
||||
@@ -1,31 +1,35 @@
|
||||
# InputManager::GetButtonDown
|
||||
|
||||
获取相关状态或对象。
|
||||
查询一个具名逻辑按钮是否在本帧刚被按下。
|
||||
|
||||
```cpp
|
||||
bool GetButtonDown(const Containers::String& buttonName) const;
|
||||
```
|
||||
|
||||
该方法声明于 `XCEngine/Input/InputManager.h`，当前页面用于固定 `InputManager` 类目录下的方法级 canonical 路径。
|
||||
## 行为说明
|
||||
|
||||
**参数：**
|
||||
- `buttonName` - 参数语义详见头文件声明。
|
||||
当前实现把逻辑按钮当作 `KeyCode` 别名处理，因此这个方法等价于对映射后的键调用 `IsKeyPressed()`。
|
||||
|
||||
**返回：** `bool` - 返回值语义详见头文件声明。
|
||||
如果按钮名未注册，返回 `false`。
|
||||
|
||||
**示例：**
|
||||
## 参数
|
||||
|
||||
- `buttonName` - 逻辑按钮名称。
|
||||
|
||||
## 返回值
|
||||
|
||||
- `bool` - 该按钮是否在本帧刚被按下。
|
||||
|
||||
## 示例
|
||||
|
||||
```cpp
|
||||
#include <XCEngine/Input/InputManager.h>
|
||||
|
||||
void Example() {
|
||||
XCEngine::Input::InputManager object;
|
||||
// 根据上下文补齐参数后调用 InputManager::GetButtonDown(...)。
|
||||
(void)object;
|
||||
if (XCEngine::Input::InputManager::Get().GetButtonDown("Fire1")) {
|
||||
// ...
|
||||
}
|
||||
```
|
||||
|
||||
## 相关文档
|
||||
|
||||
- [返回类总览](InputManager.md)
|
||||
- [返回模块目录](../Input.md)
|
||||
- [返回类型总览](InputManager.md)
|
||||
- [GetButton](GetButton.md)
|
||||
- [GetButtonUp](GetButtonUp.md)
|
||||
|
||||
@@ -1,31 +1,32 @@
|
||||
# InputManager::GetButtonUp
|
||||
|
||||
获取相关状态或对象。
|
||||
查询一个具名逻辑按钮当前是否处于抬起状态。
|
||||
|
||||
```cpp
|
||||
bool GetButtonUp(const Containers::String& buttonName) const;
|
||||
```
|
||||
|
||||
该方法声明于 `XCEngine/Input/InputManager.h`，当前页面用于固定 `InputManager` 类目录下的方法级 canonical 路径。
|
||||
## 行为说明
|
||||
|
||||
**参数：**
|
||||
- `buttonName` - 参数语义详见头文件声明。
|
||||
如果按钮名已注册，当前实现会对映射后的键调用 `IsKeyUp()`。如果按钮名未注册，当前实现直接返回 `true`。
|
||||
|
||||
**返回：** `bool` - 返回值语义详见头文件声明。
|
||||
这个“未注册也算 Up”是当前行为，不一定符合所有上层代码的直觉。
|
||||
|
||||
**示例：**
|
||||
## 参数
|
||||
|
||||
- `buttonName` - 逻辑按钮名称。
|
||||
|
||||
## 返回值
|
||||
|
||||
- `bool` - 当前是否处于抬起状态；未注册按钮也会返回 `true`。
|
||||
|
||||
## 示例
|
||||
|
||||
```cpp
|
||||
#include <XCEngine/Input/InputManager.h>
|
||||
|
||||
void Example() {
|
||||
XCEngine::Input::InputManager object;
|
||||
// 根据上下文补齐参数后调用 InputManager::GetButtonUp(...)。
|
||||
(void)object;
|
||||
}
|
||||
bool released = XCEngine::Input::InputManager::Get().GetButtonUp("Jump");
|
||||
```
|
||||
|
||||
## 相关文档
|
||||
|
||||
- [返回类总览](InputManager.md)
|
||||
- [返回模块目录](../Input.md)
|
||||
- [返回类型总览](InputManager.md)
|
||||
- [GetButton](GetButton.md)
|
||||
|
||||
@@ -1,30 +1,30 @@
|
||||
# InputManager::GetMouseDelta
|
||||
|
||||
获取相关状态或对象。
|
||||
读取当前帧保存的鼠标位移。
|
||||
|
||||
```cpp
|
||||
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
|
||||
#include <XCEngine/Input/InputManager.h>
|
||||
|
||||
void Example() {
|
||||
XCEngine::Input::InputManager object;
|
||||
// 根据上下文补齐参数后调用 InputManager::GetMouseDelta(...)。
|
||||
(void)object;
|
||||
}
|
||||
auto delta = XCEngine::Input::InputManager::Get().GetMouseDelta();
|
||||
```
|
||||
|
||||
## 相关文档
|
||||
|
||||
- [返回类总览](InputManager.md)
|
||||
- [返回模块目录](../Input.md)
|
||||
- [返回类型总览](InputManager.md)
|
||||
- [ProcessMouseMove](ProcessMouseMove.md)
|
||||
- [Update](Update.md)
|
||||
|
||||
@@ -1,30 +1,28 @@
|
||||
# InputManager::GetMousePosition
|
||||
|
||||
获取相关状态或对象。
|
||||
读取当前保存的鼠标位置。
|
||||
|
||||
```cpp
|
||||
Math::Vector2 GetMousePosition() const;
|
||||
```
|
||||
|
||||
该方法声明于 `XCEngine/Input/InputManager.h`，当前页面用于固定 `InputManager` 类目录下的方法级 canonical 路径。
|
||||
## 行为说明
|
||||
|
||||
**参数：** 无。
|
||||
当前实现直接返回内部 `m_mousePosition`。该值由 [ProcessMouseMove](ProcessMouseMove.md) 或鼠标按钮/滚轮事件携带的位置间接更新。
|
||||
|
||||
**返回：** `Math::Vector2` - 返回值语义详见头文件声明。
|
||||
如果尚未收到任何鼠标输入，默认值通常是零向量。
|
||||
|
||||
**示例：**
|
||||
## 返回值
|
||||
|
||||
- `Math::Vector2` - 当前鼠标位置。
|
||||
|
||||
## 示例
|
||||
|
||||
```cpp
|
||||
#include <XCEngine/Input/InputManager.h>
|
||||
|
||||
void Example() {
|
||||
XCEngine::Input::InputManager object;
|
||||
// 根据上下文补齐参数后调用 InputManager::GetMousePosition(...)。
|
||||
(void)object;
|
||||
}
|
||||
auto pos = XCEngine::Input::InputManager::Get().GetMousePosition();
|
||||
```
|
||||
|
||||
## 相关文档
|
||||
|
||||
- [返回类总览](InputManager.md)
|
||||
- [返回模块目录](../Input.md)
|
||||
- [返回类型总览](InputManager.md)
|
||||
- [ProcessMouseMove](ProcessMouseMove.md)
|
||||
|
||||
@@ -1,30 +1,27 @@
|
||||
# InputManager::GetMouseScrollDelta
|
||||
|
||||
获取相关状态或对象。
|
||||
读取当前帧保存的滚轮增量。
|
||||
|
||||
```cpp
|
||||
float GetMouseScrollDelta() const;
|
||||
```
|
||||
|
||||
该方法声明于 `XCEngine/Input/InputManager.h`，当前页面用于固定 `InputManager` 类目录下的方法级 canonical 路径。
|
||||
## 行为说明
|
||||
|
||||
**参数：** 无。
|
||||
当前实现返回内部 `m_mouseScrollDelta`。该值在 [ProcessMouseWheel](ProcessMouseWheel.md) 中被直接覆盖，而不是累加，并会在 [Update](Update.md) 时重置为 `0.0f`。
|
||||
|
||||
**返回：** `float` - 返回值语义详见头文件声明。
|
||||
## 返回值
|
||||
|
||||
**示例：**
|
||||
- `float` - 当前帧保存的滚轮增量。
|
||||
|
||||
## 示例
|
||||
|
||||
```cpp
|
||||
#include <XCEngine/Input/InputManager.h>
|
||||
|
||||
void Example() {
|
||||
XCEngine::Input::InputManager object;
|
||||
// 根据上下文补齐参数后调用 InputManager::GetMouseScrollDelta(...)。
|
||||
(void)object;
|
||||
}
|
||||
float scroll = XCEngine::Input::InputManager::Get().GetMouseScrollDelta();
|
||||
```
|
||||
|
||||
## 相关文档
|
||||
|
||||
- [返回类总览](InputManager.md)
|
||||
- [返回模块目录](../Input.md)
|
||||
- [返回类型总览](InputManager.md)
|
||||
- [ProcessMouseWheel](ProcessMouseWheel.md)
|
||||
- [Update](Update.md)
|
||||
|
||||
@@ -1,31 +1,32 @@
|
||||
# InputManager::GetTouch
|
||||
|
||||
获取相关状态或对象。
|
||||
读取指定索引的触点状态。
|
||||
|
||||
```cpp
|
||||
TouchState GetTouch(int index) const;
|
||||
```
|
||||
|
||||
该方法声明于 `XCEngine/Input/InputManager.h`，当前页面用于固定 `InputManager` 类目录下的方法级 canonical 路径。
|
||||
## 行为说明
|
||||
|
||||
**参数：**
|
||||
- `index` - 参数语义详见头文件声明。
|
||||
如果 `index` 合法，当前实现返回 `m_touches[index]` 的拷贝；否则返回默认构造的 `TouchState{}`。
|
||||
|
||||
**返回：** `TouchState` - 返回值语义详见头文件声明。
|
||||
由于当前公开代码路径并不会填充 `m_touches`，这个接口大多数情况下只会返回默认值。
|
||||
|
||||
**示例：**
|
||||
## 参数
|
||||
|
||||
- `index` - 触点索引。
|
||||
|
||||
## 返回值
|
||||
|
||||
- `TouchState` - 指定触点状态；非法索引时为默认构造值。
|
||||
|
||||
## 示例
|
||||
|
||||
```cpp
|
||||
#include <XCEngine/Input/InputManager.h>
|
||||
|
||||
void Example() {
|
||||
XCEngine::Input::InputManager object;
|
||||
// 根据上下文补齐参数后调用 InputManager::GetTouch(...)。
|
||||
(void)object;
|
||||
}
|
||||
auto touch = XCEngine::Input::InputManager::Get().GetTouch(0);
|
||||
```
|
||||
|
||||
## 相关文档
|
||||
|
||||
- [返回类总览](InputManager.md)
|
||||
- [返回模块目录](../Input.md)
|
||||
- [返回类型总览](InputManager.md)
|
||||
- [GetTouchCount](GetTouchCount.md)
|
||||
|
||||
@@ -1,30 +1,26 @@
|
||||
# InputManager::GetTouchCount
|
||||
|
||||
获取相关状态或对象。
|
||||
读取当前已保存的触点数量。
|
||||
|
||||
```cpp
|
||||
int GetTouchCount() const;
|
||||
```
|
||||
|
||||
该方法声明于 `XCEngine/Input/InputManager.h`，当前页面用于固定 `InputManager` 类目录下的方法级 canonical 路径。
|
||||
## 行为说明
|
||||
|
||||
**参数：** 无。
|
||||
当前实现直接返回 `m_touches.size()`。因为现有公开代码路径没有填充触摸状态，所以在当前版本里它通常为 `0`。
|
||||
|
||||
**返回：** `int` - 返回值语义详见头文件声明。
|
||||
## 返回值
|
||||
|
||||
**示例：**
|
||||
- `int` - 当前触点数量。
|
||||
|
||||
## 示例
|
||||
|
||||
```cpp
|
||||
#include <XCEngine/Input/InputManager.h>
|
||||
|
||||
void Example() {
|
||||
XCEngine::Input::InputManager object;
|
||||
// 根据上下文补齐参数后调用 InputManager::GetTouchCount(...)。
|
||||
(void)object;
|
||||
}
|
||||
int count = XCEngine::Input::InputManager::Get().GetTouchCount();
|
||||
```
|
||||
|
||||
## 相关文档
|
||||
|
||||
- [返回类总览](InputManager.md)
|
||||
- [返回模块目录](../Input.md)
|
||||
- [返回类型总览](InputManager.md)
|
||||
- [GetTouch](GetTouch.md)
|
||||
|
||||
@@ -1,31 +1,45 @@
|
||||
# InputManager::Initialize
|
||||
|
||||
初始化内部状态。
|
||||
初始化输入状态缓存并注册默认逻辑映射。
|
||||
|
||||
```cpp
|
||||
void Initialize(void* platformWindowHandle);
|
||||
```
|
||||
|
||||
该方法声明于 `XCEngine/Input/InputManager.h`，当前页面用于固定 `InputManager` 类目录下的方法级 canonical 路径。
|
||||
## 行为说明
|
||||
|
||||
**参数：**
|
||||
- `platformWindowHandle` - 参数语义详见头文件声明。
|
||||
当前实现是幂等的：如果已经初始化，直接返回。
|
||||
|
||||
**返回：** `void` - 无返回值。
|
||||
首次初始化时，它会：
|
||||
|
||||
**示例：**
|
||||
- 保存 `platformWindowHandle`
|
||||
- 分配 256 槽键盘状态数组
|
||||
- 分配 5 槽鼠标按键状态数组
|
||||
- 分配 32 槽按钮瞬时状态数组
|
||||
- 注册默认轴和按钮映射
|
||||
- 把 `m_initialized` 设为 `true`
|
||||
|
||||
当前没有做的事情：
|
||||
|
||||
- 不会清空事件监听器
|
||||
- 不会校验窗口句柄
|
||||
- 不会启动平台事件循环
|
||||
|
||||
## 参数
|
||||
|
||||
- `platformWindowHandle` - 平台窗口句柄；当前会保存下来，但 `InputManager` 本身不直接使用它。
|
||||
|
||||
## 返回值
|
||||
|
||||
- 无。
|
||||
|
||||
## 示例
|
||||
|
||||
```cpp
|
||||
#include <XCEngine/Input/InputManager.h>
|
||||
|
||||
void Example() {
|
||||
XCEngine::Input::InputManager object;
|
||||
// 根据上下文补齐参数后调用 InputManager::Initialize(...)。
|
||||
(void)object;
|
||||
}
|
||||
XCEngine::Input::InputManager::Get().Initialize(windowHandle);
|
||||
```
|
||||
|
||||
## 相关文档
|
||||
|
||||
- [返回类总览](InputManager.md)
|
||||
- [返回模块目录](../Input.md)
|
||||
- [返回类型总览](InputManager.md)
|
||||
- [Shutdown](Shutdown.md)
|
||||
|
||||
@@ -6,58 +6,89 @@
|
||||
|
||||
**头文件**: `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) | 获取相关状态或对象。 |
|
||||
| [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) | 公开方法，详见头文件声明。 |
|
||||
| [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) - 返回 `Input` 平行目录
|
||||
- [API 总索引](../../../main.md) - 返回顶层索引
|
||||
- [当前模块](../Input.md)
|
||||
- [InputAxis](../InputAxis/InputAxis.md)
|
||||
- [InputEvent](../InputEvent/InputEvent.md)
|
||||
- [Input Flow And Frame Semantics](../../../_guides/Input/Input-Flow-and-Frame-Semantics.md)
|
||||
|
||||
@@ -1,31 +1,36 @@
|
||||
# InputManager::IsKeyDown
|
||||
|
||||
查询当前状态。
|
||||
查询一个键当前是否按下。
|
||||
|
||||
```cpp
|
||||
bool IsKeyDown(KeyCode key) const;
|
||||
```
|
||||
|
||||
该方法声明于 `XCEngine/Input/InputManager.h`，当前页面用于固定 `InputManager` 类目录下的方法级 canonical 路径。
|
||||
## 行为说明
|
||||
|
||||
**参数：**
|
||||
- `key` - 参数语义详见头文件声明。
|
||||
当前实现会：
|
||||
|
||||
**返回：** `bool` - 返回值语义详见头文件声明。
|
||||
- 如果未初始化，返回 `false`
|
||||
- 把 `KeyCode` 强转成数组下标
|
||||
- 如果下标越界，返回 `false`
|
||||
- 否则返回 `m_keyDown[index]`
|
||||
|
||||
**示例：**
|
||||
## 参数
|
||||
|
||||
- `key` - 要查询的键。
|
||||
|
||||
## 返回值
|
||||
|
||||
- `bool` - 当前是否按下。
|
||||
|
||||
## 示例
|
||||
|
||||
```cpp
|
||||
#include <XCEngine/Input/InputManager.h>
|
||||
|
||||
void Example() {
|
||||
XCEngine::Input::InputManager object;
|
||||
// 根据上下文补齐参数后调用 InputManager::IsKeyDown(...)。
|
||||
(void)object;
|
||||
}
|
||||
bool held = XCEngine::Input::InputManager::Get().IsKeyDown(XCEngine::Input::KeyCode::A);
|
||||
```
|
||||
|
||||
## 相关文档
|
||||
|
||||
- [返回类总览](InputManager.md)
|
||||
- [返回模块目录](../Input.md)
|
||||
- [返回类型总览](InputManager.md)
|
||||
- [IsKeyPressed](IsKeyPressed.md)
|
||||
- [IsKeyUp](IsKeyUp.md)
|
||||
|
||||
@@ -1,31 +1,39 @@
|
||||
# InputManager::IsKeyPressed
|
||||
|
||||
查询当前状态。
|
||||
查询一个键是否在本帧刚被按下。
|
||||
|
||||
```cpp
|
||||
bool IsKeyPressed(KeyCode key) const;
|
||||
```
|
||||
|
||||
该方法声明于 `XCEngine/Input/InputManager.h`，当前页面用于固定 `InputManager` 类目录下的方法级 canonical 路径。
|
||||
## 行为说明
|
||||
|
||||
**参数：**
|
||||
- `key` - 参数语义详见头文件声明。
|
||||
|
||||
**返回：** `bool` - 返回值语义详见头文件声明。
|
||||
|
||||
**示例：**
|
||||
当前实现判断条件是：
|
||||
|
||||
```cpp
|
||||
#include <XCEngine/Input/InputManager.h>
|
||||
m_keyDownThisFrame[index] && !m_keyDownLastFrame[index]
|
||||
```
|
||||
|
||||
void Example() {
|
||||
XCEngine::Input::InputManager object;
|
||||
// 根据上下文补齐参数后调用 InputManager::IsKeyPressed(...)。
|
||||
(void)object;
|
||||
所以它表示的是“从上一帧到当前帧的按下边沿”。要得到正确结果，必须保证 [Update](Update.md) 每帧只在固定边界调用一次。
|
||||
|
||||
## 参数
|
||||
|
||||
- `key` - 要查询的键。
|
||||
|
||||
## 返回值
|
||||
|
||||
- `bool` - 当前帧是否刚按下。
|
||||
|
||||
## 示例
|
||||
|
||||
```cpp
|
||||
if (XCEngine::Input::InputManager::Get().IsKeyPressed(XCEngine::Input::KeyCode::Space)) {
|
||||
// ...
|
||||
}
|
||||
```
|
||||
|
||||
## 相关文档
|
||||
|
||||
- [返回类总览](InputManager.md)
|
||||
- [返回模块目录](../Input.md)
|
||||
- [返回类型总览](InputManager.md)
|
||||
- [Update](Update.md)
|
||||
- [IsKeyDown](IsKeyDown.md)
|
||||
|
||||
@@ -1,31 +1,29 @@
|
||||
# InputManager::IsKeyUp
|
||||
|
||||
查询当前状态。
|
||||
查询一个键当前是否处于抬起状态。
|
||||
|
||||
```cpp
|
||||
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() {
|
||||
XCEngine::Input::InputManager object;
|
||||
// 根据上下文补齐参数后调用 InputManager::IsKeyUp(...)。
|
||||
(void)object;
|
||||
}
|
||||
```
|
||||
- `key` - 要查询的键。
|
||||
|
||||
## 返回值
|
||||
|
||||
- `bool` - 当前是否抬起。
|
||||
|
||||
## 相关文档
|
||||
|
||||
- [返回类总览](InputManager.md)
|
||||
- [返回模块目录](../Input.md)
|
||||
- [返回类型总览](InputManager.md)
|
||||
- [IsKeyDown](IsKeyDown.md)
|
||||
|
||||
@@ -1,31 +1,31 @@
|
||||
# InputManager::IsMouseButtonClicked
|
||||
|
||||
查询当前状态。
|
||||
查询鼠标按键是否在本帧刚被按下。
|
||||
|
||||
```cpp
|
||||
bool IsMouseButtonClicked(MouseButton button) const;
|
||||
```
|
||||
|
||||
该方法声明于 `XCEngine/Input/InputManager.h`，当前页面用于固定 `InputManager` 类目录下的方法级 canonical 路径。
|
||||
## 行为说明
|
||||
|
||||
**参数：**
|
||||
- `button` - 参数语义详见头文件声明。
|
||||
|
||||
**返回：** `bool` - 返回值语义详见头文件声明。
|
||||
|
||||
**示例：**
|
||||
当前实现与 `IsKeyPressed` 类似，判断条件是：
|
||||
|
||||
```cpp
|
||||
#include <XCEngine/Input/InputManager.h>
|
||||
|
||||
void Example() {
|
||||
XCEngine::Input::InputManager object;
|
||||
// 根据上下文补齐参数后调用 InputManager::IsMouseButtonClicked(...)。
|
||||
(void)object;
|
||||
}
|
||||
m_mouseButtonDownThisFrame[index] && !m_mouseButtonDownLastFrame[index]
|
||||
```
|
||||
|
||||
它表示的是“本帧按下边沿”，而不是完整的点击手势。
|
||||
|
||||
## 参数
|
||||
|
||||
- `button` - 要查询的鼠标按键。
|
||||
|
||||
## 返回值
|
||||
|
||||
- `bool` - 当前帧是否刚被按下。
|
||||
|
||||
## 相关文档
|
||||
|
||||
- [返回类总览](InputManager.md)
|
||||
- [返回模块目录](../Input.md)
|
||||
- [返回类型总览](InputManager.md)
|
||||
- [IsMouseButtonDown](IsMouseButtonDown.md)
|
||||
- [Update](Update.md)
|
||||
|
||||
@@ -1,31 +1,24 @@
|
||||
# InputManager::IsMouseButtonDown
|
||||
|
||||
查询当前状态。
|
||||
查询鼠标按键当前是否按下。
|
||||
|
||||
```cpp
|
||||
bool IsMouseButtonDown(MouseButton button) const;
|
||||
```
|
||||
|
||||
该方法声明于 `XCEngine/Input/InputManager.h`，当前页面用于固定 `InputManager` 类目录下的方法级 canonical 路径。
|
||||
## 行为说明
|
||||
|
||||
**参数：**
|
||||
- `button` - 参数语义详见头文件声明。
|
||||
如果未初始化或按钮索引越界，当前实现返回 `false`。否则返回 `m_mouseButtonDown[index]`。
|
||||
|
||||
**返回：** `bool` - 返回值语义详见头文件声明。
|
||||
## 参数
|
||||
|
||||
**示例：**
|
||||
- `button` - 要查询的鼠标按键。
|
||||
|
||||
```cpp
|
||||
#include <XCEngine/Input/InputManager.h>
|
||||
## 返回值
|
||||
|
||||
void Example() {
|
||||
XCEngine::Input::InputManager object;
|
||||
// 根据上下文补齐参数后调用 InputManager::IsMouseButtonDown(...)。
|
||||
(void)object;
|
||||
}
|
||||
```
|
||||
- `bool` - 当前是否按下。
|
||||
|
||||
## 相关文档
|
||||
|
||||
- [返回类总览](InputManager.md)
|
||||
- [返回模块目录](../Input.md)
|
||||
- [返回类型总览](InputManager.md)
|
||||
- [IsMouseButtonUp](IsMouseButtonUp.md)
|
||||
|
||||
@@ -1,31 +1,24 @@
|
||||
# InputManager::IsMouseButtonUp
|
||||
|
||||
查询当前状态。
|
||||
查询鼠标按键当前是否处于抬起状态。
|
||||
|
||||
```cpp
|
||||
bool IsMouseButtonUp(MouseButton button) const;
|
||||
```
|
||||
|
||||
该方法声明于 `XCEngine/Input/InputManager.h`，当前页面用于固定 `InputManager` 类目录下的方法级 canonical 路径。
|
||||
## 行为说明
|
||||
|
||||
**参数：**
|
||||
- `button` - 参数语义详见头文件声明。
|
||||
如果未初始化，当前实现返回 `true`；否则返回 `!IsMouseButtonDown(button)`。这和键盘的 `IsKeyUp` 语义一致。
|
||||
|
||||
**返回：** `bool` - 返回值语义详见头文件声明。
|
||||
## 参数
|
||||
|
||||
**示例：**
|
||||
- `button` - 要查询的鼠标按键。
|
||||
|
||||
```cpp
|
||||
#include <XCEngine/Input/InputManager.h>
|
||||
## 返回值
|
||||
|
||||
void Example() {
|
||||
XCEngine::Input::InputManager object;
|
||||
// 根据上下文补齐参数后调用 InputManager::IsMouseButtonUp(...)。
|
||||
(void)object;
|
||||
}
|
||||
```
|
||||
- `bool` - 当前是否抬起。
|
||||
|
||||
## 相关文档
|
||||
|
||||
- [返回类总览](InputManager.md)
|
||||
- [返回模块目录](../Input.md)
|
||||
- [返回类型总览](InputManager.md)
|
||||
- [IsMouseButtonDown](IsMouseButtonDown.md)
|
||||
|
||||
@@ -1,30 +1,34 @@
|
||||
# InputManager::OnKeyEvent
|
||||
|
||||
公开方法，详见头文件声明。
|
||||
获取键盘事件通道。
|
||||
|
||||
```cpp
|
||||
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
|
||||
#include <XCEngine/Input/InputManager.h>
|
||||
|
||||
void Example() {
|
||||
XCEngine::Input::InputManager object;
|
||||
// 根据上下文补齐参数后调用 InputManager::OnKeyEvent(...)。
|
||||
(void)object;
|
||||
}
|
||||
auto id = XCEngine::Input::InputManager::Get().OnKeyEvent().Subscribe(
|
||||
[](const XCEngine::Input::KeyEvent& e) {}
|
||||
);
|
||||
```
|
||||
|
||||
## 相关文档
|
||||
|
||||
- [返回类总览](InputManager.md)
|
||||
- [返回模块目录](../Input.md)
|
||||
- [返回类型总览](InputManager.md)
|
||||
- [ProcessKeyDown](ProcessKeyDown.md)
|
||||
- [ProcessKeyUp](ProcessKeyUp.md)
|
||||
|
||||
@@ -1,30 +1,20 @@
|
||||
# InputManager::OnMouseButton
|
||||
|
||||
公开方法，详见头文件声明。
|
||||
获取鼠标按键事件通道。
|
||||
|
||||
```cpp
|
||||
Core::Event<const MouseButtonEvent&>& OnMouseButton();
|
||||
```
|
||||
|
||||
该方法声明于 `XCEngine/Input/InputManager.h`，当前页面用于固定 `InputManager` 类目录下的方法级 canonical 路径。
|
||||
## 行为说明
|
||||
|
||||
**参数：** 无。
|
||||
当前事件会在 [ProcessMouseButton](ProcessMouseButton.md) 中同步触发。它适合 UI、编辑器工具和测试代码订阅鼠标按键变化。
|
||||
|
||||
**返回：** `Core::Event<const MouseButtonEvent&>&` - 返回值语义详见头文件声明。
|
||||
## 返回值
|
||||
|
||||
**示例：**
|
||||
|
||||
```cpp
|
||||
#include <XCEngine/Input/InputManager.h>
|
||||
|
||||
void Example() {
|
||||
XCEngine::Input::InputManager object;
|
||||
// 根据上下文补齐参数后调用 InputManager::OnMouseButton(...)。
|
||||
(void)object;
|
||||
}
|
||||
```
|
||||
- `Core::Event<const MouseButtonEvent&>&` - 鼠标按键事件通道。
|
||||
|
||||
## 相关文档
|
||||
|
||||
- [返回类总览](InputManager.md)
|
||||
- [返回模块目录](../Input.md)
|
||||
- [返回类型总览](InputManager.md)
|
||||
- [ProcessMouseButton](ProcessMouseButton.md)
|
||||
|
||||
@@ -1,30 +1,20 @@
|
||||
# InputManager::OnMouseMove
|
||||
|
||||
公开方法，详见头文件声明。
|
||||
获取鼠标移动事件通道。
|
||||
|
||||
```cpp
|
||||
Core::Event<const MouseMoveEvent&>& OnMouseMove();
|
||||
```
|
||||
|
||||
该方法声明于 `XCEngine/Input/InputManager.h`，当前页面用于固定 `InputManager` 类目录下的方法级 canonical 路径。
|
||||
## 行为说明
|
||||
|
||||
**参数：** 无。
|
||||
当前事件会在 [ProcessMouseMove](ProcessMouseMove.md) 中同步触发，回调里可以直接读取本次输入事件的位置和 delta。
|
||||
|
||||
**返回：** `Core::Event<const MouseMoveEvent&>&` - 返回值语义详见头文件声明。
|
||||
## 返回值
|
||||
|
||||
**示例：**
|
||||
|
||||
```cpp
|
||||
#include <XCEngine/Input/InputManager.h>
|
||||
|
||||
void Example() {
|
||||
XCEngine::Input::InputManager object;
|
||||
// 根据上下文补齐参数后调用 InputManager::OnMouseMove(...)。
|
||||
(void)object;
|
||||
}
|
||||
```
|
||||
- `Core::Event<const MouseMoveEvent&>&` - 鼠标移动事件通道。
|
||||
|
||||
## 相关文档
|
||||
|
||||
- [返回类总览](InputManager.md)
|
||||
- [返回模块目录](../Input.md)
|
||||
- [返回类型总览](InputManager.md)
|
||||
- [ProcessMouseMove](ProcessMouseMove.md)
|
||||
|
||||
@@ -1,30 +1,20 @@
|
||||
# InputManager::OnMouseWheel
|
||||
|
||||
公开方法，详见头文件声明。
|
||||
获取鼠标滚轮事件通道。
|
||||
|
||||
```cpp
|
||||
Core::Event<const MouseWheelEvent&>& OnMouseWheel();
|
||||
```
|
||||
|
||||
该方法声明于 `XCEngine/Input/InputManager.h`，当前页面用于固定 `InputManager` 类目录下的方法级 canonical 路径。
|
||||
## 行为说明
|
||||
|
||||
**参数：** 无。
|
||||
当前事件会在 [ProcessMouseWheel](ProcessMouseWheel.md) 中同步触发。它和 `GetMouseScrollDelta` 的区别在于：事件可以立即响应每次滚轮输入，而轮询接口只保留当前保存的一个 delta。
|
||||
|
||||
**返回：** `Core::Event<const MouseWheelEvent&>&` - 返回值语义详见头文件声明。
|
||||
## 返回值
|
||||
|
||||
**示例：**
|
||||
|
||||
```cpp
|
||||
#include <XCEngine/Input/InputManager.h>
|
||||
|
||||
void Example() {
|
||||
XCEngine::Input::InputManager object;
|
||||
// 根据上下文补齐参数后调用 InputManager::OnMouseWheel(...)。
|
||||
(void)object;
|
||||
}
|
||||
```
|
||||
- `Core::Event<const MouseWheelEvent&>&` - 鼠标滚轮事件通道。
|
||||
|
||||
## 相关文档
|
||||
|
||||
- [返回类总览](InputManager.md)
|
||||
- [返回模块目录](../Input.md)
|
||||
- [返回类型总览](InputManager.md)
|
||||
- [ProcessMouseWheel](ProcessMouseWheel.md)
|
||||
|
||||
@@ -1,30 +1,20 @@
|
||||
# InputManager::OnTextInput
|
||||
|
||||
公开方法，详见头文件声明。
|
||||
获取文本输入事件通道。
|
||||
|
||||
```cpp
|
||||
Core::Event<const TextInputEvent&>& OnTextInput();
|
||||
```
|
||||
|
||||
该方法声明于 `XCEngine/Input/InputManager.h`，当前页面用于固定 `InputManager` 类目录下的方法级 canonical 路径。
|
||||
## 行为说明
|
||||
|
||||
**参数：** 无。
|
||||
当前事件会在 [ProcessTextInput](ProcessTextInput.md) 中同步触发。它适合接 UI 输入框、控制台和编辑器文本输入，而不是通用按键绑定逻辑。
|
||||
|
||||
**返回：** `Core::Event<const TextInputEvent&>&` - 返回值语义详见头文件声明。
|
||||
## 返回值
|
||||
|
||||
**示例：**
|
||||
|
||||
```cpp
|
||||
#include <XCEngine/Input/InputManager.h>
|
||||
|
||||
void Example() {
|
||||
XCEngine::Input::InputManager object;
|
||||
// 根据上下文补齐参数后调用 InputManager::OnTextInput(...)。
|
||||
(void)object;
|
||||
}
|
||||
```
|
||||
- `Core::Event<const TextInputEvent&>&` - 文本输入事件通道。
|
||||
|
||||
## 相关文档
|
||||
|
||||
- [返回类总览](InputManager.md)
|
||||
- [返回模块目录](../Input.md)
|
||||
- [返回类型总览](InputManager.md)
|
||||
- [ProcessTextInput](ProcessTextInput.md)
|
||||
|
||||
@@ -1,36 +1,37 @@
|
||||
# InputManager::ProcessKeyDown
|
||||
|
||||
公开方法，详见头文件声明。
|
||||
向输入系统注入一个按键按下事件。
|
||||
|
||||
```cpp
|
||||
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
|
||||
#include <XCEngine/Input/InputManager.h>
|
||||
- `key` - 键值。
|
||||
- `repeat` - 是否为重复按键事件。
|
||||
- `alt` - Alt 修饰键状态。
|
||||
- `ctrl` - Ctrl 修饰键状态。
|
||||
- `shift` - Shift 修饰键状态。
|
||||
- `meta` - Meta 修饰键状态。
|
||||
|
||||
void Example() {
|
||||
XCEngine::Input::InputManager object;
|
||||
// 根据上下文补齐参数后调用 InputManager::ProcessKeyDown(...)。
|
||||
(void)object;
|
||||
}
|
||||
```
|
||||
## 返回值
|
||||
|
||||
- 无。
|
||||
|
||||
## 相关文档
|
||||
|
||||
- [返回类总览](InputManager.md)
|
||||
- [返回模块目录](../Input.md)
|
||||
- [返回类型总览](InputManager.md)
|
||||
- [OnKeyEvent](OnKeyEvent.md)
|
||||
- [ProcessKeyUp](ProcessKeyUp.md)
|
||||
|
||||
@@ -1,35 +1,36 @@
|
||||
# InputManager::ProcessKeyUp
|
||||
|
||||
公开方法，详见头文件声明。
|
||||
向输入系统注入一个按键抬起事件。
|
||||
|
||||
```cpp
|
||||
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() {
|
||||
XCEngine::Input::InputManager object;
|
||||
// 根据上下文补齐参数后调用 InputManager::ProcessKeyUp(...)。
|
||||
(void)object;
|
||||
}
|
||||
```
|
||||
- `key` - 键值。
|
||||
- `alt` - Alt 修饰键状态。
|
||||
- `ctrl` - Ctrl 修饰键状态。
|
||||
- `shift` - Shift 修饰键状态。
|
||||
- `meta` - Meta 修饰键状态。
|
||||
|
||||
## 返回值
|
||||
|
||||
- 无。
|
||||
|
||||
## 相关文档
|
||||
|
||||
- [返回类总览](InputManager.md)
|
||||
- [返回模块目录](../Input.md)
|
||||
- [返回类型总览](InputManager.md)
|
||||
- [ProcessKeyDown](ProcessKeyDown.md)
|
||||
- [OnKeyEvent](OnKeyEvent.md)
|
||||
|
||||
@@ -1,34 +1,36 @@
|
||||
# InputManager::ProcessMouseButton
|
||||
|
||||
公开方法，详见头文件声明。
|
||||
向输入系统注入一个鼠标按键事件。
|
||||
|
||||
```cpp
|
||||
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() {
|
||||
XCEngine::Input::InputManager object;
|
||||
// 根据上下文补齐参数后调用 InputManager::ProcessMouseButton(...)。
|
||||
(void)object;
|
||||
}
|
||||
```
|
||||
- `button` - 鼠标按键。
|
||||
- `pressed` - `true` 表示按下，`false` 表示释放。
|
||||
- `x` - 事件位置 X。
|
||||
- `y` - 事件位置 Y。
|
||||
|
||||
## 返回值
|
||||
|
||||
- 无。
|
||||
|
||||
## 相关文档
|
||||
|
||||
- [返回类总览](InputManager.md)
|
||||
- [返回模块目录](../Input.md)
|
||||
- [返回类型总览](InputManager.md)
|
||||
- [OnMouseButton](OnMouseButton.md)
|
||||
- [IsMouseButtonClicked](IsMouseButtonClicked.md)
|
||||
|
||||
@@ -1,34 +1,36 @@
|
||||
# InputManager::ProcessMouseMove
|
||||
|
||||
公开方法，详见头文件声明。
|
||||
向输入系统注入一个鼠标移动事件。
|
||||
|
||||
```cpp
|
||||
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() {
|
||||
XCEngine::Input::InputManager object;
|
||||
// 根据上下文补齐参数后调用 InputManager::ProcessMouseMove(...)。
|
||||
(void)object;
|
||||
}
|
||||
```
|
||||
- `x` - 当前鼠标位置 X。
|
||||
- `y` - 当前鼠标位置 Y。
|
||||
- `deltaX` - 相对位移 X。
|
||||
- `deltaY` - 相对位移 Y。
|
||||
|
||||
## 返回值
|
||||
|
||||
- 无。
|
||||
|
||||
## 相关文档
|
||||
|
||||
- [返回类总览](InputManager.md)
|
||||
- [返回模块目录](../Input.md)
|
||||
- [返回类型总览](InputManager.md)
|
||||
- [OnMouseMove](OnMouseMove.md)
|
||||
- [GetMouseDelta](GetMouseDelta.md)
|
||||
|
||||
@@ -1,33 +1,34 @@
|
||||
# InputManager::ProcessMouseWheel
|
||||
|
||||
公开方法，详见头文件声明。
|
||||
向输入系统注入一个鼠标滚轮事件。
|
||||
|
||||
```cpp
|
||||
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() {
|
||||
XCEngine::Input::InputManager object;
|
||||
// 根据上下文补齐参数后调用 InputManager::ProcessMouseWheel(...)。
|
||||
(void)object;
|
||||
}
|
||||
```
|
||||
- `delta` - 滚轮增量。
|
||||
- `x` - 鼠标位置 X。
|
||||
- `y` - 鼠标位置 Y。
|
||||
|
||||
## 返回值
|
||||
|
||||
- 无。
|
||||
|
||||
## 相关文档
|
||||
|
||||
- [返回类总览](InputManager.md)
|
||||
- [返回模块目录](../Input.md)
|
||||
- [返回类型总览](InputManager.md)
|
||||
- [OnMouseWheel](OnMouseWheel.md)
|
||||
- [GetMouseScrollDelta](GetMouseScrollDelta.md)
|
||||
|
||||
@@ -1,31 +1,32 @@
|
||||
# InputManager::ProcessTextInput
|
||||
|
||||
公开方法，详见头文件声明。
|
||||
向输入系统注入一个文本输入事件。
|
||||
|
||||
```cpp
|
||||
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() {
|
||||
XCEngine::Input::InputManager object;
|
||||
// 根据上下文补齐参数后调用 InputManager::ProcessTextInput(...)。
|
||||
(void)object;
|
||||
}
|
||||
```
|
||||
- `c` - 输入字符。
|
||||
|
||||
## 返回值
|
||||
|
||||
- 无。
|
||||
|
||||
## 相关文档
|
||||
|
||||
- [返回类总览](InputManager.md)
|
||||
- [返回模块目录](../Input.md)
|
||||
- [返回类型总览](InputManager.md)
|
||||
- [OnTextInput](OnTextInput.md)
|
||||
|
||||
@@ -1,31 +1,35 @@
|
||||
# InputManager::RegisterAxis
|
||||
|
||||
注册对象、回调或映射。
|
||||
注册或覆盖一个具名逻辑轴。
|
||||
|
||||
```cpp
|
||||
void RegisterAxis(const InputAxis& axis);
|
||||
```
|
||||
|
||||
该方法声明于 `XCEngine/Input/InputManager.h`，当前页面用于固定 `InputManager` 类目录下的方法级 canonical 路径。
|
||||
## 行为说明
|
||||
|
||||
**参数：**
|
||||
- `axis` - 参数语义详见头文件声明。
|
||||
|
||||
**返回：** `void` - 无返回值。
|
||||
|
||||
**示例：**
|
||||
当前实现会执行：
|
||||
|
||||
```cpp
|
||||
#include <XCEngine/Input/InputManager.h>
|
||||
|
||||
void Example() {
|
||||
XCEngine::Input::InputManager object;
|
||||
// 根据上下文补齐参数后调用 InputManager::RegisterAxis(...)。
|
||||
(void)object;
|
||||
}
|
||||
m_axes[axis.GetName()] = axis;
|
||||
```
|
||||
|
||||
因此：
|
||||
|
||||
- 同名轴会被覆盖
|
||||
- `InputAxis` 会按值复制进管理器
|
||||
- 后续再修改原始 `axis` 对象不会影响管理器中的副本
|
||||
|
||||
## 参数
|
||||
|
||||
- `axis` - 轴配置对象。
|
||||
|
||||
## 返回值
|
||||
|
||||
- 无。
|
||||
|
||||
## 相关文档
|
||||
|
||||
- [返回类总览](InputManager.md)
|
||||
- [返回模块目录](../Input.md)
|
||||
- [返回类型总览](InputManager.md)
|
||||
- [GetAxis](GetAxis.md)
|
||||
- [ClearAxes](ClearAxes.md)
|
||||
|
||||
@@ -1,32 +1,26 @@
|
||||
# InputManager::RegisterButton
|
||||
|
||||
注册对象、回调或映射。
|
||||
注册或覆盖一个具名逻辑按钮。
|
||||
|
||||
```cpp
|
||||
void RegisterButton(const Containers::String& name, KeyCode key);
|
||||
```
|
||||
|
||||
该方法声明于 `XCEngine/Input/InputManager.h`，当前页面用于固定 `InputManager` 类目录下的方法级 canonical 路径。
|
||||
## 行为说明
|
||||
|
||||
**参数：**
|
||||
- `name` - 参数语义详见头文件声明。
|
||||
- `key` - 参数语义详见头文件声明。
|
||||
当前实现只保存 `name -> key` 的映射关系，不会创建更复杂的动作状态机。逻辑按钮本质上只是一个有名字的 `KeyCode` 别名。
|
||||
|
||||
**返回：** `void` - 无返回值。
|
||||
## 参数
|
||||
|
||||
**示例：**
|
||||
- `name` - 逻辑按钮名称。
|
||||
- `key` - 对应的按键。
|
||||
|
||||
```cpp
|
||||
#include <XCEngine/Input/InputManager.h>
|
||||
## 返回值
|
||||
|
||||
void Example() {
|
||||
XCEngine::Input::InputManager object;
|
||||
// 根据上下文补齐参数后调用 InputManager::RegisterButton(...)。
|
||||
(void)object;
|
||||
}
|
||||
```
|
||||
- 无。
|
||||
|
||||
## 相关文档
|
||||
|
||||
- [返回类总览](InputManager.md)
|
||||
- [返回模块目录](../Input.md)
|
||||
- [返回类型总览](InputManager.md)
|
||||
- [GetButton](GetButton.md)
|
||||
- [ClearAxes](ClearAxes.md)
|
||||
|
||||
@@ -1,30 +1,34 @@
|
||||
# InputManager::Shutdown
|
||||
|
||||
关闭并清理内部状态。
|
||||
清空输入状态缓存和逻辑映射。
|
||||
|
||||
```cpp
|
||||
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;
|
||||
// 根据上下文补齐参数后调用 InputManager::Shutdown(...)。
|
||||
(void)object;
|
||||
}
|
||||
```
|
||||
- 事件监听器
|
||||
- `m_touches`
|
||||
- 鼠标位置缓存
|
||||
|
||||
## 返回值
|
||||
|
||||
- 无。
|
||||
|
||||
## 相关文档
|
||||
|
||||
- [返回类总览](InputManager.md)
|
||||
- [返回模块目录](../Input.md)
|
||||
- [返回类型总览](InputManager.md)
|
||||
- [Initialize](Initialize.md)
|
||||
|
||||
@@ -1,31 +1,36 @@
|
||||
# InputManager::Update
|
||||
|
||||
更新运行时状态。
|
||||
推进输入系统的帧边界并清理瞬时状态。
|
||||
|
||||
```cpp
|
||||
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() {
|
||||
XCEngine::Input::InputManager object;
|
||||
// 根据上下文补齐参数后调用 InputManager::Update(...)。
|
||||
(void)object;
|
||||
}
|
||||
```
|
||||
- `deltaTime` - 当前未使用，但保留在接口中。
|
||||
|
||||
## 返回值
|
||||
|
||||
- 无。
|
||||
|
||||
## 相关文档
|
||||
|
||||
- [返回类总览](InputManager.md)
|
||||
- [返回模块目录](../Input.md)
|
||||
- [返回类型总览](InputManager.md)
|
||||
- [IsKeyPressed](IsKeyPressed.md)
|
||||
- [IsMouseButtonClicked](IsMouseButtonClicked.md)
|
||||
|
||||
@@ -1,29 +1,19 @@
|
||||
# InputModule::~InputModule()
|
||||
# InputModule::Destructor
|
||||
|
||||
销毁对象并释放相关资源。
|
||||
以基类指针安全销毁平台输入后端。
|
||||
|
||||
```cpp
|
||||
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)
|
||||
- [返回模块目录](../Input.md)
|
||||
- [返回类型总览](InputModule.md)
|
||||
|
||||
@@ -1,34 +1,29 @@
|
||||
# InputModule::HandleMessage
|
||||
|
||||
公开方法，详见头文件声明。
|
||||
处理一条平台窗口消息并把它翻译成引擎输入事件。
|
||||
|
||||
```cpp
|
||||
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
|
||||
#include <XCEngine/Input/InputModule.h>
|
||||
- `hwnd` - 平台窗口句柄或等价标识。
|
||||
- `msg` - 平台消息类型。
|
||||
- `wParam` - 平台消息参数 1。
|
||||
- `lParam` - 平台消息参数 2。
|
||||
|
||||
void Example() {
|
||||
XCEngine::Input::InputModule object;
|
||||
// 根据上下文补齐参数后调用 InputModule::HandleMessage(...)。
|
||||
(void)object;
|
||||
}
|
||||
```
|
||||
## 返回值
|
||||
|
||||
- 无。
|
||||
|
||||
## 相关文档
|
||||
|
||||
- [返回类总览](InputModule.md)
|
||||
- [返回模块目录](../Input.md)
|
||||
- [返回类型总览](InputModule.md)
|
||||
- [WindowsInputModule](../../Platform/Windows/WindowsInputModule/WindowsInputModule.md)
|
||||
|
||||
@@ -1,31 +1,24 @@
|
||||
# InputModule::Initialize
|
||||
|
||||
初始化内部状态。
|
||||
初始化平台输入后端。
|
||||
|
||||
```cpp
|
||||
virtual void Initialize(void* windowHandle) = 0;
|
||||
```
|
||||
|
||||
该方法声明于 `XCEngine/Input/InputModule.h`，当前页面用于固定 `InputModule` 类目录下的方法级 canonical 路径。
|
||||
## 行为说明
|
||||
|
||||
**参数：**
|
||||
- `windowHandle` - 参数语义详见头文件声明。
|
||||
平台实现通常会在这里保存窗口句柄、建立必要状态，并准备接收平台消息。`InputModule` 本身不规定更具体的初始化流程。
|
||||
|
||||
**返回：** `void` - 无返回值。
|
||||
## 参数
|
||||
|
||||
**示例：**
|
||||
- `windowHandle` - 平台窗口句柄或等价对象。
|
||||
|
||||
```cpp
|
||||
#include <XCEngine/Input/InputModule.h>
|
||||
## 返回值
|
||||
|
||||
void Example() {
|
||||
XCEngine::Input::InputModule object;
|
||||
// 根据上下文补齐参数后调用 InputModule::Initialize(...)。
|
||||
(void)object;
|
||||
}
|
||||
```
|
||||
- 无。
|
||||
|
||||
## 相关文档
|
||||
|
||||
- [返回类总览](InputModule.md)
|
||||
- [返回模块目录](../Input.md)
|
||||
- [返回类型总览](InputModule.md)
|
||||
- [Shutdown](Shutdown.md)
|
||||
|
||||
@@ -6,29 +6,39 @@
|
||||
|
||||
**头文件**: `XCEngine/Input/InputModule.h`
|
||||
|
||||
**描述**: 定义 `XCEngine/Input` 子目录中的 `InputModule` public API。
|
||||
**描述**: 定义平台输入桥接层的最小接口，把操作系统消息翻译成 `InputManager` 可消费的调用。
|
||||
|
||||
## 概述
|
||||
|
||||
`InputModule.h` 是 `XCEngine/Input` 子目录 下的 public header，当前页面作为平行目录中的 canonical 总览，用于汇总该头文件暴露的主要声明。
|
||||
`InputModule` 代表“输入后端适配器”这一层。它本身不保存全局输入状态，职责是从平台窗口系统接收原始消息，然后调用 `InputManager::Process*` 把这些消息转换成引擎内部统一格式。
|
||||
|
||||
## 声明概览
|
||||
这层拆分的价值在于：
|
||||
|
||||
| 声明 | 类型 | 说明 |
|
||||
|------|------|------|
|
||||
| `InputModule` | `class` | 头文件中的公开声明。 |
|
||||
- 游戏代码只依赖 `InputManager`，不直接依赖 Win32、GLFW 或其它平台 API。
|
||||
- 各平台后端可以各自决定如何接收事件，但最后都汇总到同一套引擎输入状态。
|
||||
|
||||
## 公共方法
|
||||
## 当前实现中的位置
|
||||
|
||||
| 方法 | 描述 |
|
||||
- [WindowsInputModule](../../Platform/Windows/WindowsInputModule/WindowsInputModule.md) 是当前代码库里的实际实现。
|
||||
- `InputModule` 本身只定义抽象接口，不提供默认逻辑。
|
||||
|
||||
## 线程语义
|
||||
|
||||
- 具体线程语义取决于平台后端。
|
||||
- 当前 Windows 路径假定输入消息和 `InputManager` 更新都发生在窗口线程或主线程。
|
||||
|
||||
## 公开方法
|
||||
|
||||
| 方法 | 说明 |
|
||||
|------|------|
|
||||
| [~InputModule()](Destructor.md) | 销毁对象并释放相关资源。 |
|
||||
| [Initialize](Initialize.md) | 初始化内部状态。 |
|
||||
| [Shutdown](Shutdown.md) | 关闭并清理内部状态。 |
|
||||
| [PumpEvents](PumpEvents.md) | 公开方法，详见头文件声明。 |
|
||||
| [HandleMessage](HandleMessage.md) | 公开方法，详见头文件声明。 |
|
||||
| [Destructor](Destructor.md) | 虚析构函数。 |
|
||||
| [Initialize](Initialize.md) | 初始化平台输入后端。 |
|
||||
| [Shutdown](Shutdown.md) | 关闭平台输入后端。 |
|
||||
| [PumpEvents](PumpEvents.md) | 主动轮询平台事件。 |
|
||||
| [HandleMessage](HandleMessage.md) | 处理一条平台消息。 |
|
||||
|
||||
## 相关文档
|
||||
|
||||
- [当前目录](../Input.md) - 返回 `Input` 平行目录
|
||||
- [API 总索引](../../../main.md) - 返回顶层索引
|
||||
- [当前模块](../Input.md)
|
||||
- [WindowsInputModule](../../Platform/Windows/WindowsInputModule/WindowsInputModule.md)
|
||||
- [Input Flow And Frame Semantics](../../../_guides/Input/Input-Flow-and-Frame-Semantics.md)
|
||||
|
||||
@@ -1,30 +1,20 @@
|
||||
# InputModule::PumpEvents
|
||||
|
||||
公开方法，详见头文件声明。
|
||||
主动轮询平台事件。
|
||||
|
||||
```cpp
|
||||
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)
|
||||
- [返回模块目录](../Input.md)
|
||||
- [返回类型总览](InputModule.md)
|
||||
- [HandleMessage](HandleMessage.md)
|
||||
|
||||
@@ -1,30 +1,20 @@
|
||||
# InputModule::Shutdown
|
||||
|
||||
关闭并清理内部状态。
|
||||
关闭平台输入后端并释放相关状态。
|
||||
|
||||
```cpp
|
||||
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)
|
||||
- [返回模块目录](../Input.md)
|
||||
- [返回类型总览](InputModule.md)
|
||||
- [Initialize](Initialize.md)
|
||||
|
||||
@@ -6,106 +6,84 @@
|
||||
|
||||
**头文件**: `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` | 头文件中的公开声明。 |
|
||||
| `MouseButton` | `enum class` | 头文件中的公开声明。 |
|
||||
| `JoystickAxis` | `enum class` | 头文件中的公开声明。 |
|
||||
| `Left` | `0` | 左键 |
|
||||
| `Right` | `1` | 右键 |
|
||||
| `Middle` | `2` | 中键 |
|
||||
| `Button4` | `3` | 扩展键 4 |
|
||||
| `Button5` | `4` | 扩展键 5 |
|
||||
|
||||
## 枚举值
|
||||
`MouseButton` 当前数值唯一，并与 `InputManager` 的 5 槽鼠标按键状态数组对应。
|
||||
|
||||
| 枚举值 | 数值 | 描述 |
|
||||
|--------|------|------|
|
||||
| `None` | `0` | 枚举项。 |
|
||||
| `A` | `4` | 枚举项。 |
|
||||
| `B` | `5` | 枚举项。 |
|
||||
| `C` | `6` | 枚举项。 |
|
||||
| `D` | `7` | 枚举项。 |
|
||||
| `E` | `8` | 枚举项。 |
|
||||
| `F` | `9` | 枚举项。 |
|
||||
| `G` | `10` | 枚举项。 |
|
||||
| `H` | `11` | 枚举项。 |
|
||||
| `I` | `12` | 枚举项。 |
|
||||
| `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` | 枚举项。 |
|
||||
## JoystickAxis
|
||||
|
||||
| 值 | 底层值 | 说明 |
|
||||
|------|------|------|
|
||||
| `LeftX` | `0` | 左摇杆 X 轴 |
|
||||
| `LeftY` | `1` | 左摇杆 Y 轴 |
|
||||
| `RightX` | `2` | 右摇杆 X 轴 |
|
||||
| `RightY` | `3` | 右摇杆 Y 轴 |
|
||||
| `LeftTrigger` | `4` | 左扳机 |
|
||||
| `RightTrigger` | `5` | 右扳机 |
|
||||
|
||||
当前 `InputManager` 还没有对应的摇杆状态存储与更新逻辑，因此这些枚举更多是为未来扩展预留。
|
||||
|
||||
## 相关文档
|
||||
|
||||
- [当前目录](../Input.md) - 返回 `Input` 平行目录
|
||||
- [API 总索引](../../../main.md) - 返回顶层索引
|
||||
- [当前模块](../Input.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
115
docs/api/_guides/Input/Input-Flow-and-Frame-Semantics.md
Normal 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)
|
||||
@@ -1,12 +1,12 @@
|
||||
# API 文档重构状态
|
||||
|
||||
**生成时间**: `2026-03-26 17:25:36`
|
||||
**生成时间**: `2026-03-26 17:39:11`
|
||||
|
||||
**来源**: `docs/api/_tools/audit_api_docs.py`
|
||||
|
||||
## 摘要
|
||||
|
||||
- Markdown 页面数（全部）: `2442`
|
||||
- Markdown 页面数（全部）: `2443`
|
||||
- Markdown 页面数（canonical）: `2436`
|
||||
- Public headers 数: `185`
|
||||
- 有效头文件引用数（全部）: `185`
|
||||
|
||||
Reference in New Issue
Block a user