重构键盘输入为 IKeyboardState 接口，消除 App 层对 SDL 的直接依赖

重构键盘输入为 IKeyboardState 接口，消除 App 层对 SDL 的直接依赖 - 新增 IKeyboardState 抽象接口及 SdlKeyboardState/EvdevKeyboardState 实现 - PlayerController 改用 IKeyboardState 替代直接调用 SDL_GetKeyboardState - 移除 Camera2D.h 中对 Core 私有头文件 Camera.h 的引用 - 将 Timer.h 从 Core/Core 移至 Core/Platform，符合架构边界规范 - 键盘输入优先级调整为高于指针输入
2026-06-10 15:22:30 +08:00
parent fb216de107
commit e00fc1799d
15 changed files with 164 additions and 28 deletions
@@ -0,0 +1,64 @@
+# Architecture Boundaries
+
+This document defines the boundary between **Core** (engine library) and **Apps** (application layer) in the IMX6U-Game project.
+
+## Public API (App may include)
+
+App code should only include headers from these Core subdirectories:
+
+| Subdirectory | Contents |
+|---|---|
+| `Core/RenderData/` | Color, Image, Sprite, Tilemap, BoundingBox, BitmapFont |
+| `Core/Math/` | Vector2, Vector3, Vector4, Matrix4x4, MathUtil |
+| `Core/Platform/` | Display, ButtonInput, IKeyboardState, PointerInput, AudioInput, AudioOutput, IPhotoSensor, TimeSource, Timer, DefaultHardware |
+| `Core/Draw2D/` | DrawContext |
+
+## Private API (App must not include)
+
+These subdirectories are Core internals. App code must not include headers from them or reference their types directly.
+
+| Subdirectory | Contents |
+|---|---|
+| `Core/Core/` | FrameBuffer, DepthBuffer, Renderer |
+| `Core/Scene/` | Camera, Mesh, Model, Transform, Vertex |
+| `Core/Rasterizer/` | Rasterizer, TriangleRasterizer |
+| `Core/Shading/` | BlinnPhongShader, ShaderTypes |
+
+## Rules
+
+1. **Dependency direction**: Core must never depend on Apps. Apps depend on Core through the public API only.
+2. **Platform isolation**: No `#include <SDL.h>`, `#include <alsa*>`, or `#include <linux/input.h>` outside `src/Core/Platform/`. App code accesses hardware through Platform interfaces (`IButtonInput`, `IKeyboardState`, `IPointerInput`, etc.).
+3. **Interface usage**: App code should use abstract interfaces from Platform, not concrete implementation classes. Use `DefaultHardware.h` typedefs when you need a concrete type.
+4. **No Core private types in App headers**: App headers must not forward-declare or reference types from private Core subdirectories.
+
+## Violation Checklist
+
+Use this during code review:
+
+- [ ] No `#include <SDL.h>` outside `src/Core/Platform/`
+- [ ] No `#include <alsa*>` outside `src/Core/Platform/`
+- [ ] No `#include <linux/input.h>` outside `src/Core/Platform/`
+- [ ] App code includes only from public subdirectories (RenderData, Math, Platform, Draw2D)
+- [ ] No App header forward-declares or references Core private types (Scene, Rasterizer, Shading, Core/Core)
+- [ ] Core source files contain no references to App namespaces or types
+
+## Input Interface Architecture
+
+The Platform layer provides separate interfaces for different input modalities:
+
+| Interface | Purpose | Backend (Desktop) | Backend (Embedded) |
+|---|---|---|---|
+| `IButtonInput` | Single physical button | `SdlKeyboardButtonInput` | `EvdevButtonInput` |
+| `IKeyboardState` | Multi-key keyboard state | `SdlKeyboardState` | `EvdevKeyboardState` (stub) |
+| `IPointerInput` | Mouse/touch pointer | `SdlPointerInput` | `EvdevTouchInput` |
+| `IPhotoSensor` | Light sensor | `SdlPhotoSensor` | `LinuxPhotoSensor` |
+
+App code accesses these through `DefaultHardware.h` typedefs (`DefaultButtonInput`, `DefaultKeyboardState`, etc.).
+
+### Input Priority
+
+When multiple input sources are active simultaneously, keyboard input takes priority over pointer input for movement direction. This is an intentional design choice for desktop usability.
+
+### Future Consolidation
+
+When a 4th input modality is added (e.g., gamepad), consider consolidating `IButtonInput*` + `IKeyboardState*` + `IPointerInput*` into a single `IInputState` interface to prevent parameter accumulation in application classes.