diff --git a/docs/api/XCEngine/Input/Input.md b/docs/api/XCEngine/Input/Input.md index bcb88188..55daa9f4 100644 --- a/docs/api/XCEngine/Input/Input.md +++ b/docs/api/XCEngine/Input/Input.md @@ -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 平台当前的具体输入桥接实现。 ## 相关文档 diff --git a/docs/api/XCEngine/Input/InputAxis/Constructor.md b/docs/api/XCEngine/Input/InputAxis/Constructor.md index 3bd23fba..30033f0f 100644 --- a/docs/api/XCEngine/Input/InputAxis/Constructor.md +++ b/docs/api/XCEngine/Input/InputAxis/Constructor.md @@ -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 - -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) diff --git a/docs/api/XCEngine/Input/InputAxis/GetName.md b/docs/api/XCEngine/Input/InputAxis/GetName.md index 4d69db9e..d127ffa1 100644 --- a/docs/api/XCEngine/Input/InputAxis/GetName.md +++ b/docs/api/XCEngine/Input/InputAxis/GetName.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 - -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) diff --git a/docs/api/XCEngine/Input/InputAxis/GetNegativeKey.md b/docs/api/XCEngine/Input/InputAxis/GetNegativeKey.md index 04625966..d8adb8b5 100644 --- a/docs/api/XCEngine/Input/InputAxis/GetNegativeKey.md +++ b/docs/api/XCEngine/Input/InputAxis/GetNegativeKey.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 - -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) diff --git a/docs/api/XCEngine/Input/InputAxis/GetPositiveKey.md b/docs/api/XCEngine/Input/InputAxis/GetPositiveKey.md index e144287f..cf40383b 100644 --- a/docs/api/XCEngine/Input/InputAxis/GetPositiveKey.md +++ b/docs/api/XCEngine/Input/InputAxis/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 - -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) diff --git a/docs/api/XCEngine/Input/InputAxis/GetValue.md b/docs/api/XCEngine/Input/InputAxis/GetValue.md index 33b90307..cd92d0e2 100644 --- a/docs/api/XCEngine/Input/InputAxis/GetValue.md +++ b/docs/api/XCEngine/Input/InputAxis/GetValue.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 - -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) diff --git a/docs/api/XCEngine/Input/InputAxis/InputAxis.md b/docs/api/XCEngine/Input/InputAxis/InputAxis.md index 0bd6c3c9..415e19af 100644 --- a/docs/api/XCEngine/Input/InputAxis/InputAxis.md +++ b/docs/api/XCEngine/Input/InputAxis/InputAxis.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) diff --git a/docs/api/XCEngine/Input/InputAxis/SetKeys.md b/docs/api/XCEngine/Input/InputAxis/SetKeys.md index d3fb9b8a..3d81c530 100644 --- a/docs/api/XCEngine/Input/InputAxis/SetKeys.md +++ b/docs/api/XCEngine/Input/InputAxis/SetKeys.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 - -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) diff --git a/docs/api/XCEngine/Input/InputAxis/SetValue.md b/docs/api/XCEngine/Input/InputAxis/SetValue.md index 649b609a..89961094 100644 --- a/docs/api/XCEngine/Input/InputAxis/SetValue.md +++ b/docs/api/XCEngine/Input/InputAxis/SetValue.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 - -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) diff --git a/docs/api/XCEngine/Input/InputEvent/InputEvent.md b/docs/api/XCEngine/Input/InputEvent/InputEvent.md index 32d97e4f..57d9bace 100644 --- a/docs/api/XCEngine/Input/InputEvent/InputEvent.md +++ b/docs/api/XCEngine/Input/InputEvent/InputEvent.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) diff --git a/docs/api/XCEngine/Input/InputManager/ClearAxes.md b/docs/api/XCEngine/Input/InputManager/ClearAxes.md index 139b624d..05cb9352 100644 --- a/docs/api/XCEngine/Input/InputManager/ClearAxes.md +++ b/docs/api/XCEngine/Input/InputManager/ClearAxes.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 - -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) diff --git a/docs/api/XCEngine/Input/InputManager/Get.md b/docs/api/XCEngine/Input/InputManager/Get.md index 9f331f1e..4c8f7a00 100644 --- a/docs/api/XCEngine/Input/InputManager/Get.md +++ b/docs/api/XCEngine/Input/InputManager/Get.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 - -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) diff --git a/docs/api/XCEngine/Input/InputManager/GetAxis.md b/docs/api/XCEngine/Input/InputManager/GetAxis.md index a0c40d7b..845b315e 100644 --- a/docs/api/XCEngine/Input/InputManager/GetAxis.md +++ b/docs/api/XCEngine/Input/InputManager/GetAxis.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 - -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) diff --git a/docs/api/XCEngine/Input/InputManager/GetAxisRaw.md b/docs/api/XCEngine/Input/InputManager/GetAxisRaw.md index b85fbeda..4808103a 100644 --- a/docs/api/XCEngine/Input/InputManager/GetAxisRaw.md +++ b/docs/api/XCEngine/Input/InputManager/GetAxisRaw.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 - -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) diff --git a/docs/api/XCEngine/Input/InputManager/GetButton.md b/docs/api/XCEngine/Input/InputManager/GetButton.md index 4211e79e..f14dd3c3 100644 --- a/docs/api/XCEngine/Input/InputManager/GetButton.md +++ b/docs/api/XCEngine/Input/InputManager/GetButton.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 - -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) diff --git a/docs/api/XCEngine/Input/InputManager/GetButtonDown.md b/docs/api/XCEngine/Input/InputManager/GetButtonDown.md index 0cf81dab..44168b3c 100644 --- a/docs/api/XCEngine/Input/InputManager/GetButtonDown.md +++ b/docs/api/XCEngine/Input/InputManager/GetButtonDown.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 - -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) diff --git a/docs/api/XCEngine/Input/InputManager/GetButtonUp.md b/docs/api/XCEngine/Input/InputManager/GetButtonUp.md index 31e6b070..208430e7 100644 --- a/docs/api/XCEngine/Input/InputManager/GetButtonUp.md +++ b/docs/api/XCEngine/Input/InputManager/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 - -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) diff --git a/docs/api/XCEngine/Input/InputManager/GetMouseDelta.md b/docs/api/XCEngine/Input/InputManager/GetMouseDelta.md index 2f23313c..3ed62bfa 100644 --- a/docs/api/XCEngine/Input/InputManager/GetMouseDelta.md +++ b/docs/api/XCEngine/Input/InputManager/GetMouseDelta.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 - -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) diff --git a/docs/api/XCEngine/Input/InputManager/GetMousePosition.md b/docs/api/XCEngine/Input/InputManager/GetMousePosition.md index ab34bf65..c7bf0ae4 100644 --- a/docs/api/XCEngine/Input/InputManager/GetMousePosition.md +++ b/docs/api/XCEngine/Input/InputManager/GetMousePosition.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 - -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) diff --git a/docs/api/XCEngine/Input/InputManager/GetMouseScrollDelta.md b/docs/api/XCEngine/Input/InputManager/GetMouseScrollDelta.md index 2485c33d..49faa031 100644 --- a/docs/api/XCEngine/Input/InputManager/GetMouseScrollDelta.md +++ b/docs/api/XCEngine/Input/InputManager/GetMouseScrollDelta.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 - -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) diff --git a/docs/api/XCEngine/Input/InputManager/GetTouch.md b/docs/api/XCEngine/Input/InputManager/GetTouch.md index 90a6040b..b27a8592 100644 --- a/docs/api/XCEngine/Input/InputManager/GetTouch.md +++ b/docs/api/XCEngine/Input/InputManager/GetTouch.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 - -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) diff --git a/docs/api/XCEngine/Input/InputManager/GetTouchCount.md b/docs/api/XCEngine/Input/InputManager/GetTouchCount.md index f3e6886c..d52941c0 100644 --- a/docs/api/XCEngine/Input/InputManager/GetTouchCount.md +++ b/docs/api/XCEngine/Input/InputManager/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 - -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) diff --git a/docs/api/XCEngine/Input/InputManager/Initialize.md b/docs/api/XCEngine/Input/InputManager/Initialize.md index ccd0a86a..d67020d7 100644 --- a/docs/api/XCEngine/Input/InputManager/Initialize.md +++ b/docs/api/XCEngine/Input/InputManager/Initialize.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 - -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) diff --git a/docs/api/XCEngine/Input/InputManager/InputManager.md b/docs/api/XCEngine/Input/InputManager/InputManager.md index ce7dc188..e5e06218 100644 --- a/docs/api/XCEngine/Input/InputManager/InputManager.md +++ b/docs/api/XCEngine/Input/InputManager/InputManager.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) diff --git a/docs/api/XCEngine/Input/InputManager/IsKeyDown.md b/docs/api/XCEngine/Input/InputManager/IsKeyDown.md index 893d567f..aee2764d 100644 --- a/docs/api/XCEngine/Input/InputManager/IsKeyDown.md +++ b/docs/api/XCEngine/Input/InputManager/IsKeyDown.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 - -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) diff --git a/docs/api/XCEngine/Input/InputManager/IsKeyPressed.md b/docs/api/XCEngine/Input/InputManager/IsKeyPressed.md index e9a8e5ad..bf11a32a 100644 --- a/docs/api/XCEngine/Input/InputManager/IsKeyPressed.md +++ b/docs/api/XCEngine/Input/InputManager/IsKeyPressed.md @@ -1,31 +1,39 @@ # InputManager::IsKeyPressed -查询当前状态。 +查询一个键是否在本帧刚被按下。 ```cpp bool IsKeyPressed(KeyCode key) const; ``` -该方法声明于 `XCEngine/Input/InputManager.h`，当前页面用于固定 `InputManager` 类目录下的方法级 canonical 路径。 +## 行为说明 -**参数：** -- `key` - 参数语义详见头文件声明。 - -**返回：** `bool` - 返回值语义详见头文件声明。 - -**示例：** +当前实现判断条件是： ```cpp -#include +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) diff --git a/docs/api/XCEngine/Input/InputManager/IsKeyUp.md b/docs/api/XCEngine/Input/InputManager/IsKeyUp.md index 25ee0d31..d16783d3 100644 --- a/docs/api/XCEngine/Input/InputManager/IsKeyUp.md +++ b/docs/api/XCEngine/Input/InputManager/IsKeyUp.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 +## 参数 -void Example() { - XCEngine::Input::InputManager object; - // 根据上下文补齐参数后调用 InputManager::IsKeyUp(...)。 - (void)object; -} -``` +- `key` - 要查询的键。 + +## 返回值 + +- `bool` - 当前是否抬起。 ## 相关文档 -- [返回类总览](InputManager.md) -- [返回模块目录](../Input.md) +- [返回类型总览](InputManager.md) +- [IsKeyDown](IsKeyDown.md) diff --git a/docs/api/XCEngine/Input/InputManager/IsMouseButtonClicked.md b/docs/api/XCEngine/Input/InputManager/IsMouseButtonClicked.md index e77cb393..bdae76cc 100644 --- a/docs/api/XCEngine/Input/InputManager/IsMouseButtonClicked.md +++ b/docs/api/XCEngine/Input/InputManager/IsMouseButtonClicked.md @@ -1,31 +1,31 @@ # InputManager::IsMouseButtonClicked -查询当前状态。 +查询鼠标按键是否在本帧刚被按下。 ```cpp bool IsMouseButtonClicked(MouseButton button) const; ``` -该方法声明于 `XCEngine/Input/InputManager.h`，当前页面用于固定 `InputManager` 类目录下的方法级 canonical 路径。 +## 行为说明 -**参数：** -- `button` - 参数语义详见头文件声明。 - -**返回：** `bool` - 返回值语义详见头文件声明。 - -**示例：** +当前实现与 `IsKeyPressed` 类似，判断条件是： ```cpp -#include - -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) diff --git a/docs/api/XCEngine/Input/InputManager/IsMouseButtonDown.md b/docs/api/XCEngine/Input/InputManager/IsMouseButtonDown.md index a5b802f6..0620dc5a 100644 --- a/docs/api/XCEngine/Input/InputManager/IsMouseButtonDown.md +++ b/docs/api/XCEngine/Input/InputManager/IsMouseButtonDown.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 +## 返回值 -void Example() { - XCEngine::Input::InputManager object; - // 根据上下文补齐参数后调用 InputManager::IsMouseButtonDown(...)。 - (void)object; -} -``` +- `bool` - 当前是否按下。 ## 相关文档 -- [返回类总览](InputManager.md) -- [返回模块目录](../Input.md) +- [返回类型总览](InputManager.md) +- [IsMouseButtonUp](IsMouseButtonUp.md) diff --git a/docs/api/XCEngine/Input/InputManager/IsMouseButtonUp.md b/docs/api/XCEngine/Input/InputManager/IsMouseButtonUp.md index 61623563..3c0c5975 100644 --- a/docs/api/XCEngine/Input/InputManager/IsMouseButtonUp.md +++ b/docs/api/XCEngine/Input/InputManager/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 +## 返回值 -void Example() { - XCEngine::Input::InputManager object; - // 根据上下文补齐参数后调用 InputManager::IsMouseButtonUp(...)。 - (void)object; -} -``` +- `bool` - 当前是否抬起。 ## 相关文档 -- [返回类总览](InputManager.md) -- [返回模块目录](../Input.md) +- [返回类型总览](InputManager.md) +- [IsMouseButtonDown](IsMouseButtonDown.md) diff --git a/docs/api/XCEngine/Input/InputManager/OnKeyEvent.md b/docs/api/XCEngine/Input/InputManager/OnKeyEvent.md index 234b5bdd..0b088a49 100644 --- a/docs/api/XCEngine/Input/InputManager/OnKeyEvent.md +++ b/docs/api/XCEngine/Input/InputManager/OnKeyEvent.md @@ -1,30 +1,34 @@ # InputManager::OnKeyEvent -公开方法，详见头文件声明。 +获取键盘事件通道。 ```cpp Core::Event& OnKeyEvent(); ``` -该方法声明于 `XCEngine/Input/InputManager.h`，当前页面用于固定 `InputManager` 类目录下的方法级 canonical 路径。 +## 行为说明 -**参数：** 无。 +返回内部 `Core::Event` 引用。当前事件会在 [ProcessKeyDown](ProcessKeyDown.md) 和 [ProcessKeyUp](ProcessKeyUp.md) 中同步触发。 -**返回：** `Core::Event&` - 返回值语义详见头文件声明。 +需要注意： -**示例：** +- 回调执行线程就是调用 `Process*` 的线程。 +- 当前 `Shutdown()` 不会清空这个事件对象中的监听器。 + +## 返回值 + +- `Core::Event&` - 键盘事件通道。 + +## 示例 ```cpp -#include - -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) diff --git a/docs/api/XCEngine/Input/InputManager/OnMouseButton.md b/docs/api/XCEngine/Input/InputManager/OnMouseButton.md index ddda6f75..f775b4b4 100644 --- a/docs/api/XCEngine/Input/InputManager/OnMouseButton.md +++ b/docs/api/XCEngine/Input/InputManager/OnMouseButton.md @@ -1,30 +1,20 @@ # InputManager::OnMouseButton -公开方法，详见头文件声明。 +获取鼠标按键事件通道。 ```cpp Core::Event& OnMouseButton(); ``` -该方法声明于 `XCEngine/Input/InputManager.h`，当前页面用于固定 `InputManager` 类目录下的方法级 canonical 路径。 +## 行为说明 -**参数：** 无。 +当前事件会在 [ProcessMouseButton](ProcessMouseButton.md) 中同步触发。它适合 UI、编辑器工具和测试代码订阅鼠标按键变化。 -**返回：** `Core::Event&` - 返回值语义详见头文件声明。 +## 返回值 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::Input::InputManager object; - // 根据上下文补齐参数后调用 InputManager::OnMouseButton(...)。 - (void)object; -} -``` +- `Core::Event&` - 鼠标按键事件通道。 ## 相关文档 -- [返回类总览](InputManager.md) -- [返回模块目录](../Input.md) +- [返回类型总览](InputManager.md) +- [ProcessMouseButton](ProcessMouseButton.md) diff --git a/docs/api/XCEngine/Input/InputManager/OnMouseMove.md b/docs/api/XCEngine/Input/InputManager/OnMouseMove.md index 63d78ad9..65210551 100644 --- a/docs/api/XCEngine/Input/InputManager/OnMouseMove.md +++ b/docs/api/XCEngine/Input/InputManager/OnMouseMove.md @@ -1,30 +1,20 @@ # InputManager::OnMouseMove -公开方法，详见头文件声明。 +获取鼠标移动事件通道。 ```cpp Core::Event& OnMouseMove(); ``` -该方法声明于 `XCEngine/Input/InputManager.h`，当前页面用于固定 `InputManager` 类目录下的方法级 canonical 路径。 +## 行为说明 -**参数：** 无。 +当前事件会在 [ProcessMouseMove](ProcessMouseMove.md) 中同步触发，回调里可以直接读取本次输入事件的位置和 delta。 -**返回：** `Core::Event&` - 返回值语义详见头文件声明。 +## 返回值 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::Input::InputManager object; - // 根据上下文补齐参数后调用 InputManager::OnMouseMove(...)。 - (void)object; -} -``` +- `Core::Event&` - 鼠标移动事件通道。 ## 相关文档 -- [返回类总览](InputManager.md) -- [返回模块目录](../Input.md) +- [返回类型总览](InputManager.md) +- [ProcessMouseMove](ProcessMouseMove.md) diff --git a/docs/api/XCEngine/Input/InputManager/OnMouseWheel.md b/docs/api/XCEngine/Input/InputManager/OnMouseWheel.md index d2423b64..9efabd73 100644 --- a/docs/api/XCEngine/Input/InputManager/OnMouseWheel.md +++ b/docs/api/XCEngine/Input/InputManager/OnMouseWheel.md @@ -1,30 +1,20 @@ # InputManager::OnMouseWheel -公开方法，详见头文件声明。 +获取鼠标滚轮事件通道。 ```cpp Core::Event& OnMouseWheel(); ``` -该方法声明于 `XCEngine/Input/InputManager.h`，当前页面用于固定 `InputManager` 类目录下的方法级 canonical 路径。 +## 行为说明 -**参数：** 无。 +当前事件会在 [ProcessMouseWheel](ProcessMouseWheel.md) 中同步触发。它和 `GetMouseScrollDelta` 的区别在于：事件可以立即响应每次滚轮输入，而轮询接口只保留当前保存的一个 delta。 -**返回：** `Core::Event&` - 返回值语义详见头文件声明。 +## 返回值 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::Input::InputManager object; - // 根据上下文补齐参数后调用 InputManager::OnMouseWheel(...)。 - (void)object; -} -``` +- `Core::Event&` - 鼠标滚轮事件通道。 ## 相关文档 -- [返回类总览](InputManager.md) -- [返回模块目录](../Input.md) +- [返回类型总览](InputManager.md) +- [ProcessMouseWheel](ProcessMouseWheel.md) diff --git a/docs/api/XCEngine/Input/InputManager/OnTextInput.md b/docs/api/XCEngine/Input/InputManager/OnTextInput.md index 01cfe7bb..cd42d53e 100644 --- a/docs/api/XCEngine/Input/InputManager/OnTextInput.md +++ b/docs/api/XCEngine/Input/InputManager/OnTextInput.md @@ -1,30 +1,20 @@ # InputManager::OnTextInput -公开方法，详见头文件声明。 +获取文本输入事件通道。 ```cpp Core::Event& OnTextInput(); ``` -该方法声明于 `XCEngine/Input/InputManager.h`，当前页面用于固定 `InputManager` 类目录下的方法级 canonical 路径。 +## 行为说明 -**参数：** 无。 +当前事件会在 [ProcessTextInput](ProcessTextInput.md) 中同步触发。它适合接 UI 输入框、控制台和编辑器文本输入，而不是通用按键绑定逻辑。 -**返回：** `Core::Event&` - 返回值语义详见头文件声明。 +## 返回值 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::Input::InputManager object; - // 根据上下文补齐参数后调用 InputManager::OnTextInput(...)。 - (void)object; -} -``` +- `Core::Event&` - 文本输入事件通道。 ## 相关文档 -- [返回类总览](InputManager.md) -- [返回模块目录](../Input.md) +- [返回类型总览](InputManager.md) +- [ProcessTextInput](ProcessTextInput.md) diff --git a/docs/api/XCEngine/Input/InputManager/ProcessKeyDown.md b/docs/api/XCEngine/Input/InputManager/ProcessKeyDown.md index 73ac43c5..d6a9cba3 100644 --- a/docs/api/XCEngine/Input/InputManager/ProcessKeyDown.md +++ b/docs/api/XCEngine/Input/InputManager/ProcessKeyDown.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 +- `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) diff --git a/docs/api/XCEngine/Input/InputManager/ProcessKeyUp.md b/docs/api/XCEngine/Input/InputManager/ProcessKeyUp.md index 4b89e65a..e78fcf6e 100644 --- a/docs/api/XCEngine/Input/InputManager/ProcessKeyUp.md +++ b/docs/api/XCEngine/Input/InputManager/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 +## 参数 -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) diff --git a/docs/api/XCEngine/Input/InputManager/ProcessMouseButton.md b/docs/api/XCEngine/Input/InputManager/ProcessMouseButton.md index 35582503..8c8087b5 100644 --- a/docs/api/XCEngine/Input/InputManager/ProcessMouseButton.md +++ b/docs/api/XCEngine/Input/InputManager/ProcessMouseButton.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 +## 参数 -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) diff --git a/docs/api/XCEngine/Input/InputManager/ProcessMouseMove.md b/docs/api/XCEngine/Input/InputManager/ProcessMouseMove.md index 5cf68008..c1bff537 100644 --- a/docs/api/XCEngine/Input/InputManager/ProcessMouseMove.md +++ b/docs/api/XCEngine/Input/InputManager/ProcessMouseMove.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 +## 参数 -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) diff --git a/docs/api/XCEngine/Input/InputManager/ProcessMouseWheel.md b/docs/api/XCEngine/Input/InputManager/ProcessMouseWheel.md index 5b8c37b2..985bd30c 100644 --- a/docs/api/XCEngine/Input/InputManager/ProcessMouseWheel.md +++ b/docs/api/XCEngine/Input/InputManager/ProcessMouseWheel.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 +## 参数 -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) diff --git a/docs/api/XCEngine/Input/InputManager/ProcessTextInput.md b/docs/api/XCEngine/Input/InputManager/ProcessTextInput.md index 0209007f..d69e1342 100644 --- a/docs/api/XCEngine/Input/InputManager/ProcessTextInput.md +++ b/docs/api/XCEngine/Input/InputManager/ProcessTextInput.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 +## 参数 -void Example() { - XCEngine::Input::InputManager object; - // 根据上下文补齐参数后调用 InputManager::ProcessTextInput(...)。 - (void)object; -} -``` +- `c` - 输入字符。 + +## 返回值 + +- 无。 ## 相关文档 -- [返回类总览](InputManager.md) -- [返回模块目录](../Input.md) +- [返回类型总览](InputManager.md) +- [OnTextInput](OnTextInput.md) diff --git a/docs/api/XCEngine/Input/InputManager/RegisterAxis.md b/docs/api/XCEngine/Input/InputManager/RegisterAxis.md index 640763b7..5ad1e860 100644 --- a/docs/api/XCEngine/Input/InputManager/RegisterAxis.md +++ b/docs/api/XCEngine/Input/InputManager/RegisterAxis.md @@ -1,31 +1,35 @@ # InputManager::RegisterAxis -注册对象、回调或映射。 +注册或覆盖一个具名逻辑轴。 ```cpp void RegisterAxis(const InputAxis& axis); ``` -该方法声明于 `XCEngine/Input/InputManager.h`，当前页面用于固定 `InputManager` 类目录下的方法级 canonical 路径。 +## 行为说明 -**参数：** -- `axis` - 参数语义详见头文件声明。 - -**返回：** `void` - 无返回值。 - -**示例：** +当前实现会执行： ```cpp -#include - -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) diff --git a/docs/api/XCEngine/Input/InputManager/RegisterButton.md b/docs/api/XCEngine/Input/InputManager/RegisterButton.md index 27be5fdb..0f23c4f2 100644 --- a/docs/api/XCEngine/Input/InputManager/RegisterButton.md +++ b/docs/api/XCEngine/Input/InputManager/RegisterButton.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 +## 返回值 -void Example() { - XCEngine::Input::InputManager object; - // 根据上下文补齐参数后调用 InputManager::RegisterButton(...)。 - (void)object; -} -``` +- 无。 ## 相关文档 -- [返回类总览](InputManager.md) -- [返回模块目录](../Input.md) +- [返回类型总览](InputManager.md) +- [GetButton](GetButton.md) +- [ClearAxes](ClearAxes.md) diff --git a/docs/api/XCEngine/Input/InputManager/Shutdown.md b/docs/api/XCEngine/Input/InputManager/Shutdown.md index f5e79c89..f0572a72 100644 --- a/docs/api/XCEngine/Input/InputManager/Shutdown.md +++ b/docs/api/XCEngine/Input/InputManager/Shutdown.md @@ -1,30 +1,34 @@ # InputManager::Shutdown -关闭并清理内部状态。 +清空输入状态缓存和逻辑映射。 ```cpp void Shutdown(); ``` -该方法声明于 `XCEngine/Input/InputManager.h`，当前页面用于固定 `InputManager` 类目录下的方法级 canonical 路径。 +## 行为说明 -**参数：** 无。 +当前实现只有在已初始化时才会执行关闭逻辑。它会清空： -**返回：** `void` - 无返回值。 +- 键盘状态数组 +- 鼠标按键状态数组 +- 轴映射 +- 按钮映射 +- 按钮瞬时状态数组 -**示例：** +然后把 `m_platformWindowHandle` 置空，并把 `m_initialized` 设为 `false`。 -```cpp -#include +当前不会清空： -void Example() { - XCEngine::Input::InputManager object; - // 根据上下文补齐参数后调用 InputManager::Shutdown(...)。 - (void)object; -} -``` +- 事件监听器 +- `m_touches` +- 鼠标位置缓存 + +## 返回值 + +- 无。 ## 相关文档 -- [返回类总览](InputManager.md) -- [返回模块目录](../Input.md) +- [返回类型总览](InputManager.md) +- [Initialize](Initialize.md) diff --git a/docs/api/XCEngine/Input/InputManager/Update.md b/docs/api/XCEngine/Input/InputManager/Update.md index 36835bef..988a53cf 100644 --- a/docs/api/XCEngine/Input/InputManager/Update.md +++ b/docs/api/XCEngine/Input/InputManager/Update.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 +## 参数 -void Example() { - XCEngine::Input::InputManager object; - // 根据上下文补齐参数后调用 InputManager::Update(...)。 - (void)object; -} -``` +- `deltaTime` - 当前未使用，但保留在接口中。 + +## 返回值 + +- 无。 ## 相关文档 -- [返回类总览](InputManager.md) -- [返回模块目录](../Input.md) +- [返回类型总览](InputManager.md) +- [IsKeyPressed](IsKeyPressed.md) +- [IsMouseButtonClicked](IsMouseButtonClicked.md) diff --git a/docs/api/XCEngine/Input/InputModule/Destructor.md b/docs/api/XCEngine/Input/InputModule/Destructor.md index e28137da..7f723240 100644 --- a/docs/api/XCEngine/Input/InputModule/Destructor.md +++ b/docs/api/XCEngine/Input/InputModule/Destructor.md @@ -1,29 +1,19 @@ -# InputModule::~InputModule() +# InputModule::Destructor -销毁对象并释放相关资源。 +以基类指针安全销毁平台输入后端。 ```cpp virtual ~InputModule() = default; ``` -该方法声明于 `XCEngine/Input/InputModule.h`，当前页面用于固定 `InputModule` 类目录下的方法级 canonical 路径。 +## 行为说明 -**参数：** 无。 +这是虚析构函数，保证平台实现类可以通过 `InputModule*` 安全释放。当前接口本身没有默认清理逻辑，具体资源释放由派生类实现负责。 -**返回：** `void` - 无返回值。 +## 返回值 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::Input::InputModule object; - // 对象离开作用域时会自动触发析构。 -} -``` +- 无。 ## 相关文档 -- [返回类总览](InputModule.md) -- [返回模块目录](../Input.md) +- [返回类型总览](InputModule.md) diff --git a/docs/api/XCEngine/Input/InputModule/HandleMessage.md b/docs/api/XCEngine/Input/InputModule/HandleMessage.md index c756c95f..dc42ee77 100644 --- a/docs/api/XCEngine/Input/InputModule/HandleMessage.md +++ b/docs/api/XCEngine/Input/InputModule/HandleMessage.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 +- `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) diff --git a/docs/api/XCEngine/Input/InputModule/Initialize.md b/docs/api/XCEngine/Input/InputModule/Initialize.md index fd6f4b52..93db19d0 100644 --- a/docs/api/XCEngine/Input/InputModule/Initialize.md +++ b/docs/api/XCEngine/Input/InputModule/Initialize.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 +## 返回值 -void Example() { - XCEngine::Input::InputModule object; - // 根据上下文补齐参数后调用 InputModule::Initialize(...)。 - (void)object; -} -``` +- 无。 ## 相关文档 -- [返回类总览](InputModule.md) -- [返回模块目录](../Input.md) +- [返回类型总览](InputModule.md) +- [Shutdown](Shutdown.md) diff --git a/docs/api/XCEngine/Input/InputModule/InputModule.md b/docs/api/XCEngine/Input/InputModule/InputModule.md index d83e4609..bcbfca77 100644 --- a/docs/api/XCEngine/Input/InputModule/InputModule.md +++ b/docs/api/XCEngine/Input/InputModule/InputModule.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) diff --git a/docs/api/XCEngine/Input/InputModule/PumpEvents.md b/docs/api/XCEngine/Input/InputModule/PumpEvents.md index 2c64c3b0..8fbe6802 100644 --- a/docs/api/XCEngine/Input/InputModule/PumpEvents.md +++ b/docs/api/XCEngine/Input/InputModule/PumpEvents.md @@ -1,30 +1,20 @@ # InputModule::PumpEvents -公开方法，详见头文件声明。 +主动轮询平台事件。 ```cpp virtual void PumpEvents() = 0; ``` -该方法声明于 `XCEngine/Input/InputModule.h`，当前页面用于固定 `InputModule` 类目录下的方法级 canonical 路径。 +## 行为说明 -**参数：** 无。 +这个接口用于那些需要主动从平台消息队列拉取输入事件的后端。当前 Windows 实现提供了该方法，但方法体为空，因为现有路径主要通过外部窗口消息回调调用 `HandleMessage`。 -**返回：** `void` - 无返回值。 +## 返回值 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::Input::InputModule object; - // 根据上下文补齐参数后调用 InputModule::PumpEvents(...)。 - (void)object; -} -``` +- 无。 ## 相关文档 -- [返回类总览](InputModule.md) -- [返回模块目录](../Input.md) +- [返回类型总览](InputModule.md) +- [HandleMessage](HandleMessage.md) diff --git a/docs/api/XCEngine/Input/InputModule/Shutdown.md b/docs/api/XCEngine/Input/InputModule/Shutdown.md index 347bedaf..bd28e4dd 100644 --- a/docs/api/XCEngine/Input/InputModule/Shutdown.md +++ b/docs/api/XCEngine/Input/InputModule/Shutdown.md @@ -1,30 +1,20 @@ # InputModule::Shutdown -关闭并清理内部状态。 +关闭平台输入后端并释放相关状态。 ```cpp virtual void Shutdown() = 0; ``` -该方法声明于 `XCEngine/Input/InputModule.h`，当前页面用于固定 `InputModule` 类目录下的方法级 canonical 路径。 +## 行为说明 -**参数：** 无。 +平台实现通常会在这里释放窗口句柄引用、内部缓存或平台输入资源。`InputModule` 不要求它必须同时调用 `InputManager::Shutdown`，这两层生命周期是否绑在一起由上层控制。 -**返回：** `void` - 无返回值。 +## 返回值 -**示例：** - -```cpp -#include - -void Example() { - XCEngine::Input::InputModule object; - // 根据上下文补齐参数后调用 InputModule::Shutdown(...)。 - (void)object; -} -``` +- 无。 ## 相关文档 -- [返回类总览](InputModule.md) -- [返回模块目录](../Input.md) +- [返回类型总览](InputModule.md) +- [Initialize](Initialize.md) diff --git a/docs/api/XCEngine/Input/InputTypes/InputTypes.md b/docs/api/XCEngine/Input/InputTypes/InputTypes.md index 6ab025ef..dd224275 100644 --- a/docs/api/XCEngine/Input/InputTypes/InputTypes.md +++ b/docs/api/XCEngine/Input/InputTypes/InputTypes.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(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) diff --git a/docs/api/_guides/Input/Input-Flow-and-Frame-Semantics.md b/docs/api/_guides/Input/Input-Flow-and-Frame-Semantics.md new file mode 100644 index 00000000..04191eb7 --- /dev/null +++ b/docs/api/_guides/Input/Input-Flow-and-Frame-Semantics.md @@ -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) diff --git a/docs/api/_meta/rebuild-status.md b/docs/api/_meta/rebuild-status.md index d10a6a92..30aed6d6 100644 --- a/docs/api/_meta/rebuild-status.md +++ b/docs/api/_meta/rebuild-status.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`