setGameDrawFrameListener

设置小游戏图像绘制事件监听器

setGameDrawFrameListener 用于注册一个回调接口，每当游戏引擎成功渲染并绘制出一帧图像时，SDK 都会触发该回调。

这个接口通常用于性能监控、渲染同步（例如原生 UI 需要随游戏帧率更新）或自动化截图/录制等进阶场景。

---

方法声明

/**
 * 设置小游戏图像绘制事件监听器。
 * * @param listener 监听器实例。若传入 null，则取消监听，释放性能开销。
 */
void setGameDrawFrameListener(SUDRTGameHandle.GameDrawFrameListener listener);

内部接口定义

public interface GameDrawFrameListener {
    /**
     * 绘制完成后回调
     *
     * @param frameCounter 当前已绘制完成的总帧数（自游戏启动起累计）
     */
    void onDrawFrame(long frameCounter);
}

---

核心运行行为

1. 非阻塞回调：为了保证游戏渲染的绝对流畅，回调绘制监听器的逻辑与引擎内部的绘制逻辑是在不同线程执行的。
2. 异步特性：由于是异步执行，onDrawFrame 被触发的时刻并不严格等同于图像显示在屏幕上的物理时刻。它仅代表“渲染管线已完成该帧的提交”。
3. 性能开销：在高帧率（如 60FPS 或 120FPS）下，每秒会产生大量回调。如果回调函数内部逻辑过重，可能会间接导致应用层主线程卡顿或内存抖动。

---

代码示例

// 1. 定义并设置监听器
gameHandle.setGameDrawFrameListener(new SUDRTGameHandle.GameDrawFrameListener() {
    private long lastTime = System.currentTimeMillis();

    @Override
    public void onDrawFrame(long frameCounter) {
        // 计算瞬时帧率（简易示例）
        if (frameCounter % 60 == 0) {
            long currentTime = System.currentTimeMillis();
            long duration = currentTime - lastTime;
            float fps = 60000f / duration;
            Log.d("SUD_RENDER", "Current FPS: " + fps + " | Total Frames: " + frameCounter);
            lastTime = currentTime;
        }

        // 注意：如果需要在此更新原生 UI，必须切回主线程
        // runOnUiThread(() -> updateMyNativeOverlay());
    }
});

// 2. 当不再需要监控时（如进入后台），务必置空
// gameHandle.setGameDrawFrameListener(null);

---

注意事项

• 及时解绑：当业务逻辑不再需要每帧回调时，**务必调用 setGameDrawFrameListener(null)**。保持监听会产生持续的线程间通信开销。
• 禁止耗时操作：切勿在 onDrawFrame 中执行复杂的图像处理、I/O 操作或网络请求。
• UI 线程安全：该回调通常在引擎的渲染辅助线程中执行。直接在回调里修改 Android View 会触发异常，必须使用 Handler.post() 或 Activity.runOnUiThread()。

---