Pyglet 中 on_draw 回调重复触发问题的技术解析

现象描述

在 Pyglet 图形库的使用过程中，开发者 matanox 发现了一个有趣的现象：在 Wayland 桌面环境下运行 Pyglet 应用程序时，on_draw 回调函数会被连续调用两次。通过一个最小化示例程序可以清晰地观察到这一现象：

import sys
import pyglet

window = pyglet.window.Window()
image = pyglet.image.load(sys.argv[1])
window.set_size(image.height, image.width)

def update(dt):
    print(f'update')

@window.event
def on_draw():
    print(f'draw')
    image.blit(x=0, y=0, z=0)

pyglet.clock.schedule_interval(update, 1/30)
pyglet.app.event_loop.run()

程序输出显示，每次 update 调用后都会跟随两次 on_draw 调用，这种模式在程序运行过程中持续出现。

问题分析

默认绘制调度机制

经过深入分析，Pyglet 核心开发者 benmoran56 指出，这是 Pyglet 事件循环的预期行为。Pyglet 的 app.run() 方法默认会以 60Hz 的频率调度 Window.draw 操作，这是为了确保应用程序能够保持流畅的动画效果。

绘制与更新的关系

在典型的游戏循环中，更新逻辑(update)和绘制逻辑(draw)通常是分开的：

1. 更新逻辑负责计算游戏状态、处理输入等
2. 绘制逻辑负责将当前状态渲染到屏幕上

Pyglet 默认会以更高的频率触发绘制操作，这可以带来更流畅的视觉体验，即使游戏状态更新频率较低。

性能考量

开发者 matanox 进一步测试发现：

• 当 update 函数执行时间较长时，双绘制现象会消失
• 如果强制跳过第二次绘制，偶尔会出现画面闪烁

这表明系统确实需要保持一定的绘制频率来维持画面稳定性，特别是在需要与桌面环境交互的情况下。

解决方案

禁用默认绘制调度

对于需要精确控制绘制时机的应用，可以禁用 Pyglet 的默认绘制调度：

pyglet.app.event_loop.run(None)  # 禁用默认绘制调度

自定义绘制策略

在实时性要求高的应用中（如视频流处理），可以采用以下策略：

1. 完全由数据到达驱动绘制
2. 不使用固定间隔的更新调度
3. 在数据准备好后立即请求重绘

示例代码：

def on_new_frame(data):
    # 处理新帧数据
    process_frame(data)
    # 请求重绘
    window.invalid = True

@window.event
def on_draw():
    if has_new_frame:
        draw_current_frame()

平台差异与最佳实践

不同平台和桌面环境可能有不同的绘制需求：

1. Wayland/X11：可能需要更频繁的绘制来保持窗口同步
2. Windows：通常对绘制频率要求较为宽松
3. macOS：有自己特定的合成器行为

对于大多数应用，遵循 Pyglet 默认的 60Hz 绘制频率是安全的选择。只有在特定场景下（如实时视频处理、科学可视化等）才需要考虑自定义绘制策略。

结论

Pyglet 的双重绘制行为是其默认事件循环设计的合理结果，旨在提供流畅的视觉体验。开发者应根据应用需求选择合适的绘制策略：

• 普通应用：保持默认行为即可
• 高性能应用：可以自定义绘制调度
• 实时应用：完全由数据驱动绘制

理解这一机制有助于开发者更好地优化 Pyglet 应用程序的性能和响应性。