本文介绍如何使用 moderngl_window 的 `mouse_exclusivity` 属性实现真正的鼠标锁定（即光标不可移出窗口、不可见、仅提供相对位移），替代低效的轮询或外部工具方案，并附可运行示例与关键注意事项。
在基于 OpenGL 的交互式图形应用（如 Shader Toy 风格的片段着色器演示或轻量级 3D 查看器）中，实现「鼠标独占模式」（Mouse Exclusivity / Raw Input Mode）是构建沉浸式相机控制的基础——它让光标完全隐藏、不响应系统级边界限制，并持续输出平滑的相对位移（dx, dy），而非绝对屏幕坐标。这正是现代 3D 引擎（如 GLFW 默认行为）所依赖的核心机制。
moderngl_window 基于 GLFW 构建，原生支持该功能，无需切换库或引入 pyautogui 等易出错的模拟方案。关键在于启用 Window.mouse_exclusivity 属性，它会自动调用 GLFW 的 glfwSetInputMode(window, GLFW_CURSOR, GLFW_CURSOR_DISABLED)，并启用原始输入（raw mouse motion），确保跨平台（包括 Arch Linux + X11/Wayland）行为一致。
✅ 正确启用方式
只需在窗口配置类中动态设置 self.wnd.mouse_exclusivity = True 即可。推荐通过按键事件（如 C 键）实时切换，便于调试：
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.quad = mgl.geometry.quad_fs()
self.prog = self.load_program(
vertex_shader="vertex.glsl",
fragment_shader="frag.glsl"
)
self.prog["resolution"] = self.window_size
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):
# ⚠️ 注意：锁定后 x, y 恒为窗口中心（逻辑值），无实际意义
# ✅ 唯一可靠的是 dx, dy —— 未经加速/缩放的原始像素位移
if self.wnd.mouse_exclusivity:
# 示例：用于第一人称相机 yaw/pitch 更新
self._rotate_camera(dx * 0.002, dy * 0.002)
def _rotate_camera(self, delta_yaw, delta_pitch):
# 此处插入你的相机旋转逻辑（如更新 uniform）
try:
self.prog["camera_yaw"] = self.prog["camera_yaw"].value + delta_yaw
self.prog["camera_pitch"] = max(-1.5, min(1.5, self.prog["camera_pitch"].value + delta_pitch))
except KeyError:
pass
def render(self, time, frame_time):
self.ctx.clear(0.1, 0.1, 0.15)
self.prog["time"] = time
self.quad.render(self.prog)
if __name__ == "__main__":
print("? Press 'C' to toggle mouse lock/unlock")
mgl.run_window_config(App)⚠️ 关键注意事项
cursor = False ≠ mouse_exclusivity = True
cursor = False 仅隐藏光标，但光标仍可移出窗口、触发系统焦点丢失；而 mouse_exclusivity = True 才真正捕获并锁定光标，同时隐式隐藏。x, y 在锁定状态下失效
GLFW 在独占模式下不提供绝对坐标（因光标被“固定”在窗口中心），因此 mouse_position_event 中的 x, y 是恒定的伪值（通常为窗口中心）。务必只使用 dx, dy 进行运动计算，它们代表未处理的原始输入增量，精度高且无系统指针加速干扰。退出锁定需显式恢复
程序异常退出时，GLFW 通常能自动恢复光标，但为保险起见，建议在 close_event() 中添加 self.wnd.mouse_exclusivity = False 清理。-
Linux 兼容性提示（Arch/X11/Wayland）
moderngl_window 0.14+ 对 Wayland 支持已显著改善。若遇锁定失败，请确认：- 使用 glfw-x11 或 glfw-wayland 后端（通过环境变量 MODERNGL_WINDOW=glfw + export GLFW_PLATFORM=wayland 控制）；
- 用户属于 input 组（sudo usermod -aG input $USER）；
- 避免在远程桌面（如 VNC）中运行——独占模式依赖本地输入设备访问。
✅ 总结
Window.mouse_exclusivity 是 moderngl_window 提供的、符合现代图形应用标准的鼠标锁定方案：零依赖、跨平台、低延迟、语义明确。它完美替代了手动坐标钳制、pyautogui 强制归位等反模式。结合 mouse_position_event 的 dx/dy 数据流，即可快速构建稳定的第一人称视角、轨道相机或任意基于鼠标的交互逻辑。记住核心原则：锁光标用 mouse_exclusivity，读位移只取 dx/dy，一切尽在 GLFW 的优雅封装之中。
