📚 课程目录第3章使用Choreographer.FrameCallback监控帧耗时

使用 Choreographer.FrameCallback 监控帧耗时：API 使用、帧耗时计算方法、回调间隔测量

3.1 FrameCallback 接口与核心原理

Choreographer.FrameCallback 是 Android 提供给开发者直接介入帧渲染管线的唯一回调接口。每当系统准备刷新下一帧时，Choreographer 会按注册顺序依次调用所有待执行的 FrameCallback。通过该回调，开发者可以精确测量帧的生成时间、渲染耗时以及回调之间的时间间隔。

核心 API 方法：

void doFrame(long frameTimeNanos) —— 回调方法，frameTimeNanos 表示当前帧的预期渲染时间戳（纳秒，System.nanoTime() 基准）。
void postFrameCallback(FrameCallback callback) —— 注册单次回调，下一帧执行后自动移除。
void postFrameCallbackDelayed(FrameCallback callback, long delayMillis) —— 延迟注册单次回调。
void postFrameCallback(FrameCallback callback, Object ) —— 带的单次回调，用于批量取消。
void removeCallbacks(FrameCallback callback, Object ) —— 根据移除待执行的回调。

3.2 帧耗时计算模型

frameTimeNanos 是 Choreographer 预测的“理想帧时间”，而非实际开始绘制的时间。帧耗时应通过回调内部的时间戳差值计算：

单帧耗时： endNanos - startNanos，其中 startNanos 为 doFrame 入口时间，endNanos 为回调末尾时间。
帧间隔 (Frame Interval)： 本次 frameTimeNanos 减去上次 frameTimeNanos，反映系统能否按时调度帧。
掉帧检测： 当帧间隔 > 16.67ms (60fps) 或 > 11.12ms (90fps) 时，判定为跳帧 (Jank)。

常见陷阱： frameTimeNanos 是预测值，不应用作单帧耗时计算基准。实际耗时必须以 System.nanoTime() 在回调内部测量的时间为准。系统可能因输入事件、动画或渲染管线阻塞导致 frameTimeNanos 与实际执行时间产生数毫秒偏移。

3.3 回调间隔测量

回调间隔是指两次 doFrame 调用之间的真实时间差，用于识别渲染管道是否被阻塞或出现异常跳过。测量方式如下：

private long lastFrameTimeNanos = 0L;

private final Choreographer.FrameCallback frameCallback =
    new Choreographer.FrameCallback() {
        @Override
        public void doFrame(long frameTimeNanos) {
            long now = System.nanoTime();
            if (lastFrameTimeNanos != 0L) {
                // 回调间隔 = 本次实际时间 - 上次实际时间
                long callbackIntervalNs = now - lastFrameTimeNanos;
                // 帧预测间隔 = 本次预测时间 - 上次预测时间
                long frameTimeIntervalNs = frameTimeNanos - lastFrameTimeNanos;
                // 调度偏差 = 回调间隔 - 帧预测间隔
                long scheduleDeviationNs = callbackIntervalNs - frameTimeIntervalNs;

                if (callbackIntervalNs > 16_666_666L * 1.5) { // 超过目标帧间隔50%
                    Log.w("FrameMonitor", "疑似跳帧: 间隔="
                            + callbackIntervalNs / 1_000_000L + "ms");
                }
            }
            lastFrameTimeNanos = frameTimeNanos;
            // 重新注册持续监听
            Choreographer.getInstance().postFrameCallback(this);
        }
    };

// 启动监控
Choreographer.getInstance().postFrameCallback(frameCallback);

测量参数含义：

指标	计算方式	正常范围 (60fps)
回调间隔	本次实际时间 - 上次实际时间	16.67ms ± 1ms
帧预测间隔	本次 frameTimeNanos - 上次 frameTimeNanos	16.67ms ± 2ms
调度偏差	回调间隔 - 帧预测间隔	< 1ms

3.4 实现流程

初始化监控器： 在 Activity/Fragment 创建时实例化 Choreographer 实例，并调用 postFrameCallback() 注册回调。
记录时间戳： 在 doFrame 入口处通过 System.nanoTime() 记录本次开始时间。
计算帧耗时： 在回调末尾再次获取时间戳，差值即为当前帧在 UI 线程的阻塞时长。
计算回调间隔： 利用上次记录的 frameTimeNanos 或实际时间戳，计算与本次的差值。
上报与分析： 将耗时与间隔数据通过日志、指标打点或自定义回调解耦上报。
取消监听： 页面销毁时调用 removeCallbacks()，避免内存泄露和空指针。

3.5 postFrameCallback 与 postFrameCallbackVsync 的区别

方法	触发时机	典型场景	性能影响
`postFrameCallback`	下一帧 Vsync 信号到来时	帧耗时监控、自定义动画帧同步	低，回调执行完成后自动移除
`postFrameCallbackVsync` (API 29+)	下个 Vsync 信号的精确时间点	需要与硬件 Vsync 严格对齐的渲染场景	中，回调与硬件同步，可能略微增加调度延迟

从 API 29 开始，Choreographer 新增了 postFrameCallbackVsync 方法，它返回一个 FrameCallback 类型的，允许开发者更精确地控制回调与硬件 Vsync 的绑定。对于仅需帧耗时监控的场景，使用 postFrameCallback 即可满足需求，无需额外复杂度。

3.6 常见错误与调试

在 doFrame 内部执行耗时操作： 回调运行在 UI 线程，任何耗时逻辑都会直接阻塞下一帧渲染。应当仅做时间戳计算和轻量数据记录，数据处理移至后台线程。
忘记重新注册回调： postFrameCallback 是单次回掉，若需持续监控必须在 doFrame 末尾重新调用 postFrameCallback(this)，否则只执行一次。
未处理 Activity 暂停/恢复： 页面进入后台后 Choreographer 可能停止分发 Vsync；应结合生命周期在 onPause 时移除回调，onResume 时重新注册。
多 Choreographer 实例冲突： 每个 Activity 默认只有一个 Choreographer 实例，但多个 Fragment 或 View 可能各自注册回调，导致回调链过长。建议统一使用一个全局监控器。

3.7 调试与验证

在配置了 FrameCallback 监控后，通过以下命令验证回调是否正常触发：

# 开启 Choreographer 内部日志 (Android 10+)
adb shell setprop debug.choreographer.logframes 1

# 过滤帧调度日志
adb logcat -s Choreographer:I

# 验证回调间隔是否稳定，输出格式参考：
# Choreographer: Frame time: 1678949578 ns, scheduled: 1678949560 ns, delay: 18 ns

同时，利用 Android Studio 的 GPU 渲染分析工具 (Profile GPU Rendering) 或 Frame Rendering API (API 26+) 可以交叉验证帧耗时的准确性。FrameCallback 测量的耗时主要反映 UI 线程的阻塞情况，而 GPU 渲染分析则覆盖整个渲染管线的总耗时。

3.8 性能与稳定性优化

减少单次回调计算量： doFrame 中只做必要的纳秒时间记录和简单阈值判断，日志字符串拼接放在判断条件之后。
使用内存缓存避免分配： 预分配 long 型数组存储历史时间戳，避免在回调内创建新对象导致 GC 抖动。
采样上报： 连续帧间隔正常时不需输出日志，仅在检测到跳帧或耗时超过阈值时打点，减少 IO 和 CPU 开销。
利用批量管理： 若需要注册多个临时回调，使用 postFrameCallback(callback, ) 统一管理，便于在生命周期结束时一次性移除。
避免过度注册： 每个页面仅维持一个活跃的 FrameCallback 实例，多观察者模式通过内部监听列表分发，而非注册多个回调。

3.9 最佳实践代码模板

public class FrameMonitor {
    private final Choreographer choreographer = Choreographer.getInstance();
    private final FrameCallback callback;
    private long lastFrameTimeNs = 0L;
    private long lastActualTimeNs = 0L;
    private boolean isMonitoring = false;

    public FrameMonitor() {
        callback = new Choreographer.FrameCallback() {
            @Override
            public void doFrame(long frameTimeNanos) {
                long now = System.nanoTime();
                if (lastFrameTimeNs != 0L) {
                    long callbackInterval = now - lastActualTimeNs;
                    long frameInterval = frameTimeNanos - lastFrameTimeNs;
                    long scheduleDeviation = callbackInterval - frameInterval;

                    if (callbackInterval > 16_666_666L * 1.8) {
                        // 跳帧超过80%，输出警告
                        dumpJankEvent(callbackInterval, frameInterval, scheduleDeviation);
                    }
                }
                lastFrameTimeNs = frameTimeNanos;
                lastActualTimeNs = now;
                if (isMonitoring) {
                    choreographer.postFrameCallback(this);
                }
            }
        };
    }

    public void start() {
        if (!isMonitoring) {
            isMonitoring = true;
            choreographer.postFrameCallback(callback);
        }
    }

    public void stop() {
        isMonitoring = false;
        choreographer.removeCallbacks(callback, null);
        lastFrameTimeNs = 0L;
        lastActualTimeNs = 0L;
    }
}