setFrameRate: Make shouldBeSeamless an enum

Change the shouldBeSeamless parameter to an enum
in order to make the API easier to understand.

This changes
 - SurfaceControl.setFrameRate
 - Surface.setFrameRate
 - ANativeWindow_setFrameRateWithChangeStrategy
 - ASurfaceTransaction_setFrameRateWithChangeStrategy

Bug: 179116474
Test: atest SetFrameRateTest
Change-Id: I55265399238e2c95fbb90fd33a4c2513d1fc5cec

1 files changed, 29 insertions, 13 deletions

diff --git a/core/java/android/view/Surface.java b/core/java/android/view/Surface.java
index f8c4d1587f22..aa3c9d6e14f9 100644
--- a/core/java/android/view/Surface.java
+++ b/core/java/android/view/Surface.java
@@ -97,7 +97,7 @@ public class Surface implements Parcelable {
     private static native int nativeSetAutoRefreshEnabled(long nativeObject, boolean enabled);
 
     private static native int nativeSetFrameRate(
-            long nativeObject, float frameRate, int compatibility, boolean shouldBeSeamless);
+            long nativeObject, float frameRate, int compatibility, int changeFrameRateStrategy);
 
     public static final @android.annotation.NonNull Parcelable.Creator<Surface> CREATOR =
             new Parcelable.Creator<Surface>() {
@@ -226,6 +226,26 @@ public class Surface implements Parcelable {
      */
     public static final int FRAME_RATE_COMPATIBILITY_EXACT = 100;
 
+
+    /** @hide */
+    @Retention(RetentionPolicy.SOURCE)
+    @IntDef(prefix = {"CHANGE_FRAME_RATE_"},
+            value = {CHANGE_FRAME_RATE_ONLY_IF_SEAMLESS, CHANGE_FRAME_RATE_ALWAYS})
+    public @interface ChangeFrameRateStrategy {}
+
+    /**
+     * Change the frame rate only if the transition is going to be seamless.
+     */
+    public static final int CHANGE_FRAME_RATE_ONLY_IF_SEAMLESS = 0;
+
+    /**
+     * Change the frame rate even if the transition is going to be non-seamless, i.e. with visual
+     * interruptions for the user. Non-seamless switches might be used when the benefit of matching
+     * the content's frame rate outweighs the cost of the transition, for example when
+     * displaying long-running video content.
+     */
+    public static final int CHANGE_FRAME_RATE_ALWAYS = 1;
+
     /**
      * Create an empty surface, which will later be filled in by readFromParcel().
      * @hide
@@ -921,25 +941,21 @@ public class Surface implements Parcelable {
      * the display at 60fps.
      *
      * @param compatibility The frame rate compatibility of this surface. The
-     * compatibility value may influence the system's choice of display frame rate. See
-     * the FRAME_RATE_COMPATIBILITY_* values for more info.
+     * compatibility value may influence the system's choice of display frame rate.
      *
-     * @param shouldBeSeamless Whether display refresh rate transitions should be seamless. A
+     * @param changeFrameRateStrategy Whether display refresh rate transitions 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. True indicates that any frame rate changes caused by this
-     * request should be seamless. False indicates that non-seamless refresh rates are also
-     * acceptable. Non-seamless switches might be used when the benefit of matching the content's
-     * frame rate outweighs the cost of the transition, for example when displaying
-     * long-running video content.
+     * screen for a second or two.
      *
      * @throws IllegalArgumentException If frameRate or compatibility are invalid.
      */
     public void setFrameRate(@FloatRange(from = 0.0) float frameRate,
-            @FrameRateCompatibility int compatibility, boolean shouldBeSeamless) {
+            @FrameRateCompatibility int compatibility,
+            @ChangeFrameRateStrategy int changeFrameRateStrategy) {
         synchronized (mLock) {
             checkNotReleasedLocked();
             int error = nativeSetFrameRate(mNativeObject, frameRate, compatibility,
-                    shouldBeSeamless);
+                    changeFrameRateStrategy);
             if (error == -EINVAL) {
                 throw new IllegalArgumentException("Invalid argument to Surface.setFrameRate()");
             } else if (error != 0) {
@@ -952,11 +968,11 @@ public class Surface implements Parcelable {
      * Sets the intended frame rate for this surface. Any switching of refresh rates is
      * most probably going to be seamless.
      *
-     * @see #setFrameRate(float, int, boolean)
+     * @see #setFrameRate(float, int, int)
      */
     public void setFrameRate(
             @FloatRange(from = 0.0) float frameRate, @FrameRateCompatibility int compatibility) {
-        setFrameRate(frameRate, compatibility, /* shouldBeSeamless = */ true);
+        setFrameRate(frameRate, compatibility, CHANGE_FRAME_RATE_ONLY_IF_SEAMLESS);
     }
 
     /**