本文详解如何在 moderngl-window 中启用鼠标独占（mouse exclusivity）模式，实现光标自动隐藏与窗口内相对位移捕获，适用于 3d 相机控制等交互场景，无需第三方库或系统级模拟。
在基于 moderngl-window 构建的 OpenGL 应用（如交互式着色器、3D 渲染器或自定义游戏引擎）中，实现类似第一人称视角的平滑相机控制，关键在于获取稳定、连续、无边界干扰的鼠标运动输入。这正是鼠标独占模式（Mouse Exclusivity / Raw Input Mode）的核心价值：它将光标锁定在窗口中心（视觉上隐藏），并将所有鼠标移动转化为相对位移量（dx, dy），彻底规避了光标抵达屏幕边缘后停止响应、坐标跳变或焦点丢失等问题。
moderngl-window 原生支持该功能，通过 Window.mouse_exclusivity 属性即可一键启用。该属性底层依赖 GLFW 的 glfwSetInputMode(window, GLFW_CURSOR, GLFW_CURSOR_DISABLED)，在 Linux（包括 Arch）、Windows 和 macOS 上均可靠工作，无需额外依赖或权限提升。
✅ 启用鼠标独占的正确方式
在 WindowConfig 子类中，不要在类属性（如 cursor = False）中设置——那是控制光标可见性，而非独占行为。正确做法是运行时动态赋值：
self.wnd.mouse_exclusivity = True # 启用独占（同时自动隐藏光标） self.wnd.mouse_exclusivity = False # 恢复正常模式（光标可见且可移出窗口）
启用后，窗口将自动隐藏光标，并将鼠标设备置于“原始输入”模式：此时 mouse_position_event 回调中的 x 和 y 参数将恒为窗口中心坐标（通常为 (width/2, height/2)），而真正有意义的是 dx 和 dy —— 它们代表自上一帧以来鼠标的像素级相对位移，完全不受操作系统光标加速、屏幕边界限制影响，是实现 FPS 式旋转的理想输入源。
? 完整示例：可切换锁定的交互应用
以下是一个最小可用示例，支持按 C 键切换鼠标锁定状态，并实时打印相对位移：
import moderngl_window as mgl
class App(mgl.WindowConfig):
window_size = (1280, 720)
resource_dir = "src"
# 注意：此处 cursor=False 仅确保初始隐藏，不影响 exclusivity 状态
cursor = False
def __init__(self, **kwargs):
super().__init__(**kwargs)
# 可选：初始化相机参数（如 yaw/pitch）
self.yaw = 0.0
self.pitch = 0.0
def key_event(self, key, action, modifiers):
keys = self.wnd.keys
if key == keys.C and action == keys.ACTION_PRESS:
self.wnd.mouse_exclusivity = not self.wnd.mouse_exclusivity
print(f"→ Mouse exclusivity: {self.wnd.mouse_exclusivity}")
def mouse_position_event(self, x, y, dx, dy):
# 仅在独占模式下 dx/dy 才有效；非独占时 dx/dy 为 0
if self.wnd.mouse_exclusivity:
# 典型的 FPS 相机更新逻辑（需结合 time delta 防止帧率敏感）
sensitivity = 0.1
self.yaw += dx * sensitivity
self.pitch -= dy * sensitivity # Y 轴反转（OpenGL 约定）
# 限制俯仰角避免翻转
self.pitch = max(-89.0, min(89.0, self.pitch))
print(f"Camera rotation: yaw={self.yaw:.2f}°, pitch={self.pitch:.2f}°")
def render(self, time, frame_time):
self.ctx.clear(0.1, 0.1, 0.2) # 清屏背景色
# 此处插入你的渲染逻辑（如 quad.render(...)）
if __name__ == "__main__":
print("? 提示：按 C 键切换鼠标锁定模式")
print(" 锁定后移动鼠标即可控制 3D 视角")
mgl.run_window_config(App)⚠ 注意事项与最佳实践
- 事件触发时机：mouse_position_event 仅在鼠标移动时触发，且仅当 mouse_exclusivity=True 时才提供有效的 dx/dy。若需每帧读取（如结合 frame_time 计算角速度），应将位移量缓存至实例变量。
- 跨平台兼容性：mouse_exclusivity 在 moderngl-window ≥ 2.4.0 + GLFW 后端下全平台一致。确保 pip install moderngl-window[glfw] 或已安装系统级 glfw。
- 退出处理：程序异常退出时，moderngl-window 通常能自动恢复光标状态。但为保险起见，可在 __del__ 或信号处理器中显式设 self.wnd.mouse_exclusivity = False。
- 与 cursor = False 的关系：两者独立但协同——cursor=False 控制光标图标显示，mouse_exclusivity=True 控制输入捕获与坐标语义。实践中建议同时启用以获得完整体验。
- Linux 特别提示（Arch 用户）：确认已安装 glfw-x11 或 glfw-wayland（取决于你的显示服务器），并避免在 Wayland 下使用不兼容的旧版 GLFW；moderngl-window 默认优先使用 X11 后端，稳定性更佳。
通过合理利用 mouse_exclusivity，你将获得专业级的输入控制能力，为现代 OpenGL 应用构建沉浸式交互体验奠定坚实基础。
