本文详解如何使用 moderngl_window 的 mouse_exclusivity 属性实现专业级鼠标锁定，使光标完全隐藏并仅输出相对位移（dx/dy），适用于 3d 相机控制等交互场景，无需第三方库或系统级模拟。
在基于 OpenGL 的交互式渲染应用（如 ShaderToy 风格的片段着色器演示或轻量级 3D 引擎）中，实现类似第一人称视角的平滑相机控制，关键前提之一是稳定、低延迟、无边界干扰的鼠标输入。moderngl_window 原生支持 GLFW 后端，而 GLFW 提供了标准的 mouse capture（鼠标独占）机制——它并非简单隐藏光标，而是将鼠标设备置于“相对运动模式”：操作系统不再更新光标绝对位置，所有移动均以增量（delta）形式上报，且光标被逻辑锁定在窗口中心（不可见、不可移出）。这正是现代 3D 应用（如游戏、CAD 工具）所依赖的底层行为。
moderngl_window 将该能力封装为 Window.mouse_exclusivity 属性（类型为 bool）。启用后（设为 True），窗口自动隐藏光标，并切换输入模式；禁用时（False）则恢复常规绝对坐标行为与可见光标。该特性跨平台支持（Linux/macOS/Windows），在 Arch Linux 下亦可直接使用，无需 pyautogui 等轮询式“软约束”，避免了竞态、延迟和焦点丢失问题。
以下是一个完整、可运行的示例，展示如何在 moderngl_window 中启用鼠标独占并处理运动事件：
import moderngl_window as mgl
class App(mgl.WindowConfig):
window_size = (1336, 768)
resource_dir = "src"
cursor = False # 初始隐藏光标（但此时未锁定）
fullscreen = False
def __init__(self, **kwargs):
super().__init__(**kwargs)
# 初始化状态：默认不锁定，便于调试
self.wnd.mouse_exclusivity = False
def key_event(self, key, action, modifiers):
keys = self.wnd.keys
# 按 C 键切换鼠标锁定状态
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):
# ⚠️ 注意：鼠标锁定后，x 和 y 始终为窗口中心坐标（通常不变）
# 真实的旋转/移动应仅基于 dx/dy（单位：像素，有符号）
if self.wnd.mouse_exclusivity:
# 示例：累积 dx/dy 实现 yaw/pitch 控制（用于 3D 相机）
# yaw += dx * 0.002
# pitch -= dy * 0.002
pass
# 调试输出（仅在锁定时有意义）
if self.wnd.mouse_exclusivity:
print(f"Δx={dx:+6.1f}, Δy={dy:+6.1f}")
def render(self, time, frame_time):
self.ctx.clear(0.1, 0.1, 0.15) # 渲染背景色
# 此处添加您的着色器渲染逻辑（如 quad.render(...)）
if __name__ == "__main__":
print("? 提示：按 'C' 键切换鼠标锁定模式")
print(" 锁定后，鼠标不可见，移动将仅触发 dx/dy 事件")
mgl.run_window_config(App)关键要点与注意事项：
- ✅ 初始化时机：mouse_exclusivity 可在 __init__ 中直接设置（如 self.wnd.mouse_exclusivity = True），也可通过按键/事件动态切换；
- ✅ 事件处理逻辑：启用锁定后，mouse_position_event 中的 x 和 y 参数不再反映真实屏幕坐标（GLFW 会将其固定为窗口中心），因此必须忽略 x/y，仅使用 dx/dy 进行姿态计算（如相机 yaw/pitch、物体旋转）；
- ✅ 光标可见性：cursor = False 仅控制初始可见性；mouse_exclusivity = True 会强制隐藏光标并接管输入，二者协同工作；
- ⚠️ 平台兼容性：该功能依赖 GLFW 的 glfwSetInputMode(window, GLFW_CURSOR, GLFW_CURSOR_DISABLED)，在 moderngl_window 的 GLFW 上下文下稳定可用；若使用其他后端（如 SDL2），需查阅对应文档；
- ⚠️ 退出安全：务必提供明确的解锁方式（如 ESC 键），否则用户可能无法操作桌面。建议在 key_event 中加入 keys.ESCAPE 处理逻辑，强制设为 False 并调用 self.wnd.close()；
- ? 进阶提示：为获得更平滑的相机响应，可对 dx/dy 进行加权缩放（如乘以灵敏度系数）、低通滤波或帧间积分，避免快速抖动。
通过 mouse_exclusivity，你获得了与专业图形应用一致的输入体验——简洁、高效、符合平台规范。它不是“模拟锁定”，而是直接启用操作系统与 GPU 驱动协同的原生输入模式，是构建沉浸式 OpenGL 交互应用的必备基础能力。
