From 769de4ac09e2e4c2bf7ef3da987063769faa78d5 Mon Sep 17 00:00:00 2001 From: Rachel Lee Date: Mon, 28 Oct 2024 10:32:55 -0700 Subject: Define new ASurfaceTransaction_setFrameRateParams API In libandroid. Bug: 362798998 Test: atest SetFrameRateTest Flag: EXEMPT NDK Change-Id: Id52288f77bf43f4c7573c6743e5307d849490852 --- include/android/surface_control.h | 63 +++++++++++++++++++++++++++++++++++++++ 1 file changed, 63 insertions(+) (limited to 'include/android') diff --git a/include/android/surface_control.h b/include/android/surface_control.h index 8d61e772cc..fe38e86015 100644 --- a/include/android/surface_control.h +++ b/include/android/surface_control.h @@ -762,6 +762,69 @@ void ASurfaceTransaction_setFrameRateWithChangeStrategy(ASurfaceTransaction* _No int8_t changeFrameRateStrategy) __INTRODUCED_IN(31); +/** + * Sets the intended frame rate for the given \a surface_control. + * + * On devices that are capable of running the display at different frame rates, + * the system may choose a display refresh rate to better match this surface's frame + * rate. Usage of this API won't introduce frame rate throttling, or affect other + * aspects of the application's frame production pipeline. However, because the system + * may change the display refresh rate, calls to this function may result in changes + * to Choreographer callback timings, and changes to the time interval at which the + * system releases buffers back to the application. + * + * You can register for changes in the refresh rate using + * \a AChoreographer_registerRefreshRateCallback. + * + * See ASurfaceTransaction_clearFrameRate(). + * + * Available since API level 36. + * + * \param desiredMinRate The desired minimum frame rate (inclusive) for the surface, specifying that + * the surface prefers the device render rate to be at least `desiredMinRate`. + * + *

Set `desiredMinRate` = `desiredMaxRate` to indicate the surface prefers an exact frame rate. + * + *

Set `desiredMinRate` = 0 to indicate the surface has no preference + * and any frame rate is acceptable. + * + *

The value should be greater than or equal to 0. + * + * \param desiredMaxRate The desired maximum frame rate (inclusive) for the surface, specifying that + * the surface prefers the device render rate to be at most `desiredMaxRate`. + * + *

Set `desiredMaxRate` = `desiredMinRate` to indicate the surface prefers an exact frame rate. + * + *

Set `desiredMaxRate` = positive infinity to indicate the surface has no preference + * and any frame rate is acceptable. + * + *

The value should be greater than or equal to `desiredMinRate`. + * + * \param fixedSourceRate The "fixed source" frame rate of the surface if the content has an + * inherently fixed frame rate, e.g. a video that has a specific frame rate. + * + *

When the frame rate chosen for the surface is the `fixedSourceRate` or a + * multiple, the surface can render without frame pulldown, for optimal smoothness. For + * example, a 30 fps video (`fixedSourceRate`=30) renders just as smoothly on 30 fps, + * 60 fps, 90 fps, 120 fps, and so on. + * + *

Setting the fixed source rate can also be used together with a desired + * frame rate min and max via setting `desiredMinRate` and `desiredMaxRate`. This still + * means the surface's content has a fixed frame rate of `fixedSourceRate`, but additionally + * specifies the preference to be in the range [`desiredMinRate`, `desiredMaxRate`]. For example, an + * app might want to specify there is 30 fps video (`fixedSourceRate`=30) as well as a smooth + * animation on the same surface which looks good when drawing within a frame rate range such as + * [`desiredMinRate`, `desiredMaxRate`] = [60,120]. + * + * \param changeFrameRateStrategy Whether display refresh rate transitions caused by this surface + * should be seamless. A seamless transition is one that doesn't have any visual interruptions, such + * as a black screen for a second or two. + */ +void ASurfaceTransaction_setFrameRateParams( + ASurfaceTransaction* _Nonnull transaction, ASurfaceControl* _Nonnull surface_control, + float desiredMinRate, float desiredMaxRate, float fixedSourceRate, + ANativeWindow_ChangeFrameRateStrategy changeFrameRateStrategy) __INTRODUCED_IN(36); + /** * Clears the frame rate which is set for \a surface_control. * -- cgit v1.2.3-59-g8ed1b