Pyglet项目中ImageMouseCursor在Windows缩放下的问题分析与解决方案

问题背景

在Pyglet游戏开发库中，开发者发现当Windows系统启用了缩放功能(如125%缩放)时，ImageMouseCursor(自定义图像鼠标指针)会出现位置偏移和显示异常的问题。这个问题在Windows 10和Windows 11系统上均能复现。

问题现象

当系统缩放设置为100%时，自定义鼠标指针显示正常；但当缩放调整为125%时，鼠标指针会出现以下两个问题：

1. 指针位置与实际点击位置不匹配
2. 指针图像显示大小不正确

问题根源分析

经过深入调查，发现问题源于Pyglet的DPI缩放处理机制。当系统缩放改变时，鼠标坐标和图像渲染没有进行相应的缩放调整。特别值得注意的是，这个问题在默认的"real"DPI模式下不会出现，但当设置为"stretch"模式时就会显现。

技术细节

Pyglet提供了三种DPI缩放模式：

1. "real"模式：保持实际像素大小
2. "stretch"模式：拉伸内容以适应缩放
3. "auto"模式：自动选择

在"stretch"模式下，系统会报告缩放后的坐标，但图像渲染仍使用原始像素尺寸，导致位置和尺寸不匹配。

解决方案

开发者提出了两种解决方案：

1. 临时解决方案：手动调整坐标

def draw(self, x: int, y: int) -> None:
    gl.glEnable(gl.GL_BLEND)
    gl.glBlendFunc(gl.GL_SRC_ALPHA, gl.GL_ONE_MINUS_SRC_ALPHA)
    self.texture.blit((x - self.hot_x) / 1.25, (y - self.hot_y) / 1.25, 0)
    gl.glDisable(gl.GL_BLEND)

2. 永久解决方案：通过PR #1278修复，使用窗口的缩放因子自动调整：

self.texture.blit(
    (x - self.hot_x) / window.scale,
    (y - self.hot_y) / window.scale,
    0
)

最佳实践建议

对于开发者来说，处理Windows缩放问题时应注意：

1. 明确项目所需的DPI缩放模式
2. 在自定义鼠标指针时考虑窗口缩放因子
3. 测试应用在不同缩放设置下的表现
4. 优先使用Pyglet提供的窗口缩放属性(window.scale)而非硬编码缩放值

总结

Pyglet的ImageMouseCursor在Windows缩放环境下的问题展示了跨平台UI开发中常见的DPI缩放挑战。通过理解Pyglet的缩放机制和使用正确的缩放因子，开发者可以确保自定义鼠标指针在各种显示设置下都能正确显示和定位。这个问题也提醒我们，在现代高DPI显示环境下，图形应用必须妥善处理各种缩放场景。