应用可通过 Frame Rate API 将其预期帧速率告知 Android 平台,该 API 可在以 Android 11(API 级别 30)或更高版本为目标平台的应用中使用。大多数设备传统上仅支持一种显示屏刷新频率(通常为 60Hz),但这一直在变化。现在,许多设备都支持其他刷新频率,如 90Hz 或 120Hz。某些设备支持无缝切换刷新率,而其他设备会短暂显示黑屏(通常持续一秒钟)。
该 API 的主要用途是让应用能够更好地利用所有受支持的显示屏刷新频率。例如,播放调用 setFrameRate()
的 24Hz 视频可能会导致设备将屏幕刷新频率从 60Hz 更改为 120Hz。这种新的刷新频率可以实现流畅、无抖动的 24Hz 视频播放,而无需像在 60Hz 显示屏上播放同一视频那样进行 3:2 下拉。这将带来更出色的用户体验。
基本用法
Android 提供了多种访问和控制 Surface 的方法,因此 setFrameRate()
API 有多个版本。该 API 的每个版本都采用相同的参数,并且工作方式与其他版本相同:
Surface.setFrameRate()
SurfaceControl.Transaction.setFrameRate()
ANativeWindow_setFrameRate()
ASurfaceTransaction_setFrameRate()
应用无需考虑实际支持的屏幕刷新率(可通过调用 Display.getSupportedModes()
获得),以便安全地调用 setFrameRate()
。例如,即使设备仅支持 60Hz,使用应用偏好的帧速率调用 setFrameRate()
。应用的帧速率不匹配的设备将保持当前的显示刷新率。
如需了解调用 setFrameRate()
是否会导致显示刷新率发生变化,请调用 DisplayManager.registerDisplayListener()
或 AChoreographer_registerRefreshRateCallback()
注册显示屏更改通知。
调用 setFrameRate()
时,最好传入确切的帧速率,而不是四舍五入为整数。例如,在渲染以 29.97Hz 录制的视频时,请传递 29.97,而不是四舍五入到 30。
对于视频应用,应将传递给 setFrameRate()
的兼容性参数设置为 Surface.FRAME_RATE_COMPATIBILITY_FIXED_SOURCE
,以向 Android 平台提供额外的提示,即应用将使用下拉功能来适应不匹配的显示刷新率(这将导致画面卡顿)。
在某些情况下,视频界面会停止提交帧,但仍会在屏幕上显示一段时间。常见场景包括播放已到达视频结尾或用户暂停播放时。在这些情况下,请在帧速率参数设置为 0 的情况下调用 setFrameRate()
,以将 Surface 的帧速率设置清除为默认值。销毁 Surface 或者由于用户切换到其他应用而隐藏 Surface 时,不需要清除帧速率设置。仅当 Surface 仍然可见且未使用时,才需清除帧速率设置。
非流畅帧速率切换
在某些设备上,刷新频率切换可能会出现视觉中断,例如黑屏一两秒钟。这通常发生在机顶盒、电视面板和类似设备上。默认情况下,Android 框架在调用 Surface.setFrameRate()
API 时不会切换模式,以避免此类视觉中断。
有些用户更喜欢在时长较长的视频开头和结尾显示视觉插播内容。这样可以使显示屏的刷新率与视频帧速率保持一致,并避免帧速率转换失真,例如播放影片时的 3:2 下拉抖动。
因此,如果用户和应用都选择启用,则可以启用非流畅刷新率切换:
- 用户:如需选择启用此功能,用户可以启用匹配内容帧速率用户设置。
- 应用:如需选择启用,应用可以将
CHANGE_FRAME_RATE_ALWAYS
传递到setFrameRate()
。
我们建议您始终对电影等长时间运行的视频使用 CHANGE_FRAME_RATE_ALWAYS
。这是因为匹配视频帧速率的好处大于更改刷新频率时造成的中断。
其他建议
请遵循以下建议来处理常见场景。
多个 Surface
Android 平台经过精心设计,可正确处理具有不同帧速率设置的多个 surface 的情况。如果您的应用有多个帧速率不同的 Surface,请针对每个 Surface 使用正确的帧速率调用 setFrameRate()
。即使设备使用分屏或画中画模式同时运行多个应用,每个应用也可以安全地调用 setFrameRate()
来获取自己的 Surface。
平台不会更改为应用的帧速率
即使设备支持应用在调用 setFrameRate()
中指定的帧速率,有时设备也不会将显示屏切换到该刷新频率。例如,优先级较高的 Surface 可能具有不同的帧速率设置,或者设备可能处于省电模式(对显示刷新率设置限制以节省电量)。当设备未将显示屏刷新频率切换为应用的帧速率设置时,应用仍必须正常运行,即使设备在正常情况下确实进行了切换也是如此。
当显示刷新频率与应用帧速率不匹配时,应用将决定如何响应。对于视频,帧速率固定为源视频的帧速率,并且需要下拉才能显示视频内容。游戏可能会改为选择尝试以显示屏刷新频率运行,而不是保持其首选帧速率。应用不应根据平台执行的操作更改传递给 setFrameRate()
的值。无论应用如何处理平台未根据应用请求进行调整的情况,该值都应保持设为应用的首选帧速率。这样,如果设备条件发生变化,允许使用其他显示刷新率,平台就会拥有正确的信息来切换到应用的首选帧速率。
如果应用不会或无法以屏幕刷新频率运行,则应使用平台的一种设置呈现时间戳的机制,为每个帧指定呈现时间戳:
使用这些时间戳会阻止平台过早呈现应用帧,从而导致不必要的抖动。正确使用帧呈现时间戳有点棘手。对于游戏,请参阅我们的帧同步指南,详细了解如何避免画面卡顿,并考虑使用 Android Frame Pacing 库。
在某些情况下,平台可能会切换到应用在 setFrameRate()
中指定的帧速率的倍数。例如,应用可能会以 60Hz 的频率调用 setFrameRate()
,而设备可能会将显示屏切换为 120Hz。发生这种情况的原因可能是另一个应用的 Surface 的帧速率设置为 24Hz。在这种情况下,以 120Hz 运行屏幕可让 60Hz Surface 和 24Hz Surface 都无需下拉即可运行。
当显示屏以应用帧速率的倍数运行时,应用应为每个帧指定呈现时间戳,以避免不必要的抖动。对于游戏,Android Frame Pacing 库有助于正确设置帧呈现时间戳。
setFrameRate() 与 preferredDisplayModeId
WindowManager.LayoutParams.preferredDisplayModeId
是应用向平台指明其帧速率的另一种方式。某些应用只想更改显示刷新率,而不想更改其他显示模式设置(如显示分辨率)。通常,请使用 setFrameRate()
而不是 preferredDisplayModeId
。setFrameRate()
函数更易于使用,因为应用无需搜索显示模式列表即可找到具有特定帧速率的模式。
在多个 Surface 以不同的帧速率运行的情况下,setFrameRate()
可让平台有更多机会选择兼容的帧速率。例如,设想一个场景:两个应用在 Pixel 4 上以分屏模式运行,其中一个应用在播放 24Hz 视频,另一个应用在向用户显示可滚动列表。Pixel 4 支持两种屏幕刷新率:60Hz 和 90Hz。使用 preferredDisplayModeId
API 时,系统会强制视频 Surface 选择 60Hz 或 90Hz。通过使用 24Hz 的 setFrameRate()
调用 24Hz,视频 Surface 可为平台提供有关源视频帧速率的更多信息,使平台能够为显示刷新频率选择 90Hz(在这种情况下,优于 60Hz)。
不过,在某些情况下,应使用 preferredDisplayModeId
而非 setFrameRate()
,例如:
- 如果应用想要更改分辨率或其他显示模式设置,请使用
preferredDisplayModeId
。 - 仅当模式开关是轻量级且不太可能被用户注意到时,平台才会为了响应
setFrameRate()
调用而切换显示模式。如果应用更倾向于切换显示刷新率,即使需要重模式切换(例如在 Android TV 设备上),也应使用preferredDisplayModeId
。 - 如果应用无法处理以应用帧速率的倍数(这需要在每一帧上设置呈现时间戳)运行的显示屏,则应使用
preferredDisplayModeId
。
setFrameRate() 与 preferredRefreshRate
WindowManager.LayoutParams#preferredRefreshRate
会在应用窗口上设置首选帧速率,该速率适用于窗口内的所有 Surface。无论设备支持的刷新频率如何,应用都应指定其首选帧速率(类似于 setFrameRate()
),以便更好地为调度器提供应用的预期帧速率提示。
对于使用 setFrameRate()
的 Surface,会忽略 preferredRefreshRate
。一般来说,请尽可能使用 setFrameRate()
。
PreferredRefreshRate 与 preferredDisplayModeId
如果应用只想更改首选刷新率,最好使用 preferredRefreshRate
,而不是 preferredDisplayModeId
。
避免过于频繁地调用 setFrameRate()
虽然从性能方面调用 setFrameRate()
的开销并不高,但应用应避免每一帧调用 setFrameRate()
或每秒调用多次。调用 setFrameRate()
可能会导致屏幕刷新率发生变化,进而可能导致转换期间丢失帧。您应提前确定正确的帧速率并调用一次 setFrameRate()
。
游戏或其他非视频应用的使用情况
虽然视频是 setFrameRate()
API 的主要用例,但它也可用于其他应用。例如,如果游戏打算不高于 60Hz 的刷新率运行(以减少功耗并延长游戏时长),则可以调用 Surface.setFrameRate(60, Surface.FRAME_RATE_COMPATIBILITY_DEFAULT)
。这样一来,在游戏运行时,默认以 90Hz 运行的设备将改为以 60Hz 运行,这样可以避免在游戏以 60Hz 运行而显示屏以 90Hz 运行时出现抖动。
使用了 FRAME_RATE_COMPATIBILITY_FIXED_SOURCE
FRAME_RATE_COMPATIBILITY_FIXED_SOURCE
仅适用于视频应用。对于非视频用途,请使用 FRAME_RATE_COMPATIBILITY_DEFAULT
。
选择更改帧速率的策略
- 我们强烈建议应用在显示长时间运行的视频(如电影)时调用
setFrameRate(
fps, FRAME_RATE_COMPATIBILITY_FIXED_SOURCE, CHANGE_FRAME_RATE_ALWAYS)
,其中 fps 是视频的帧速率。 - 如果您预计视频播放时长不超过几分钟,我们强烈建议您不要使用
CHANGE_FRAME_RATE_ALWAYS
调用setFrameRate()
。
视频播放应用集成示例
若要在视频播放应用中集成刷新率开关,我们建议您按照以下步骤操作:
- 确定
changeFrameRateStrategy
:- 如果播放的是时长较长的视频(例如电影),请使用
MATCH_CONTENT_FRAMERATE_ALWAYS
- 如果要播放动作预告片等短视频,请使用
CHANGE_FRAME_RATE_ONLY_IF_SEAMLESS
- 如果播放的是时长较长的视频(例如电影),请使用
- 如果
changeFrameRateStrategy
为CHANGE_FRAME_RATE_ONLY_IF_SEAMLESS
,请转到第 4 步。 - 通过检查以下两个事实是否均为 true,检测是否即将发生非流畅刷新率切换:
- 无法从当前刷新率(假设为 C)无缝切换到视频的帧速率(假设为 V)。如果 C 和 V 不同,并且
Display.getMode().getAlternativeRefreshRates
不包含 V 的倍数,就会出现这种情况。 - 用户已选择启用非无缝刷新率更改。您可以通过检查
DisplayManager.getMatchContentFrameRateUserPreference
是否返回MATCH_CONTENT_FRAMERATE_ALWAYS
来检测此问题。
- 无法从当前刷新率(假设为 C)无缝切换到视频的帧速率(假设为 V)。如果 C 和 V 不同,并且
- 如果要实现流畅切换,请执行以下操作:
- 调用
setFrameRate
并向其传递fps
、FRAME_RATE_COMPATIBILITY_FIXED_SOURCE
和changeFrameRateStrategy
,其中fps
是视频的帧速率。 - 开始播放视频
- 调用
- 如果即将发生非无缝模式更改,请执行以下操作:
- 显示用户体验以通知用户。请注意,我们建议您实现一种方式,让用户能够关闭此用户体验并跳过第 5.d 步中的额外延迟。这是因为,对于切换时间较短的显示屏,我们建议的延迟时间过长。
- 调用
setFrameRate
并向其传递fps
、FRAME_RATE_COMPATIBILITY_FIXED_SOURCE
和CHANGE_FRAME_RATE_ALWAYS
,其中fps
是视频的帧速率。 - 等待
onDisplayChanged
回调。 - 等待 2 秒钟,让模式切换完成。
- 开始播放视频
只支持流畅切换的伪代码如下:
SurfaceControl.Transaction transaction = new SurfaceControl.Transaction();
transaction.setFrameRate(surfaceControl,
contentFrameRate,
FRAME_RATE_COMPATIBILITY_FIXED_SOURCE,
CHANGE_FRAME_RATE_ONLY_IF_SEAMLESS);
transaction.apply();
beginPlayback();
如上所述,支持流畅和非流畅切换的伪代码如下所示:
SurfaceControl.Transaction transaction = new SurfaceControl.Transaction();
if (isSeamlessSwitch(contentFrameRate)) {
transaction.setFrameRate(surfaceControl,
contentFrameRate,
FRAME_RATE_COMPATIBILITY_FIXED_SOURCE,
CHANGE_FRAME_RATE_ONLY_IF_SEAMLESS);
transaction.apply();
beginPlayback();
} else if (displayManager.getMatchContentFrameRateUserPreference()
== MATCH_CONTENT_FRAMERATE_ALWAYS) {
showRefreshRateSwitchUI();
sleep(shortDelaySoUserSeesUi);
displayManager.registerDisplayListener(…);
transaction.setFrameRate(surfaceControl,
contentFrameRate,
FRAME_RATE_COMPATIBILITY_FIXED_SOURCE,
CHANGE_FRAME_RATE_ALWAYS);
transaction.apply();
waitForOnDisplayChanged();
sleep(twoSeconds);
hideRefreshRateSwitchUI();
beginPlayback();
}