[MQ] Clean up ambient light APIs

Test: mmm
Flag: android.media.tv.flags.media_quality_fw
Bug: 377079429
Change-Id: I73a4a1a86bbff2358eef7da5455856a08490b312

4 files changed, 93 insertions, 12 deletions

diff --git a/media/java/android/media/quality/AmbientBacklightEvent.java b/media/java/android/media/quality/AmbientBacklightEvent.java
index 3bc6b86c0615..5c11def43209 100644
--- a/media/java/android/media/quality/AmbientBacklightEvent.java
+++ b/media/java/android/media/quality/AmbientBacklightEvent.java
@@ -16,9 +16,11 @@
 
 package android.media.quality;
 
+import android.annotation.FlaggedApi;
 import android.annotation.IntDef;
 import android.annotation.NonNull;
 import android.annotation.Nullable;
+import android.media.tv.flags.Flags;
 import android.os.Parcel;
 import android.os.Parcelable;
 
@@ -27,8 +29,10 @@ import java.lang.annotation.RetentionPolicy;
 import java.util.Objects;
 
 /**
+ * Ambient backlight event
  * @hide
  */
+@FlaggedApi(Flags.FLAG_MEDIA_QUALITY_FW)
 public final class AmbientBacklightEvent implements Parcelable {
 
     /** @hide */
@@ -64,6 +68,9 @@ public final class AmbientBacklightEvent implements Parcelable {
     @Nullable
     private final AmbientBacklightMetadata mMetadata;
 
+    /**
+     * Constructor of AmbientBacklightEvent.
+     */
     public AmbientBacklightEvent(int eventType,
             @Nullable AmbientBacklightMetadata metadata) {
         mEventType = eventType;
@@ -75,10 +82,19 @@ public final class AmbientBacklightEvent implements Parcelable {
         mMetadata = in.readParcelable(AmbientBacklightMetadata.class.getClassLoader());
     }
 
+    /**
+     * Gets event type.
+     */
     public int getEventType() {
         return mEventType;
     }
 
+    /**
+     * Gets ambient backlight metadata.
+     *
+     * @return the metadata of the event. It's non-null only for
+     * {@link #AMBIENT_BACKLIGHT_EVENT_METADATA}.
+     */
     @Nullable
     public AmbientBacklightMetadata getMetadata() {
         return mMetadata;
@@ -95,7 +111,8 @@ public final class AmbientBacklightEvent implements Parcelable {
         return 0;
     }
 
-    public static final @NonNull Parcelable.Creator<AmbientBacklightEvent> CREATOR =
+    @NonNull
+    public static final Parcelable.Creator<AmbientBacklightEvent> CREATOR =
             new Parcelable.Creator<AmbientBacklightEvent>() {
                 public AmbientBacklightEvent createFromParcel(Parcel in) {
                     return new AmbientBacklightEvent(in);
diff --git a/media/java/android/media/quality/AmbientBacklightMetadata.java b/media/java/android/media/quality/AmbientBacklightMetadata.java
index fc779348de11..9c11f9a3e560 100644
--- a/media/java/android/media/quality/AmbientBacklightMetadata.java
+++ b/media/java/android/media/quality/AmbientBacklightMetadata.java
@@ -16,6 +16,10 @@
 
 package android.media.quality;
 
+import android.annotation.FlaggedApi;
+import android.annotation.IntRange;
+import android.graphics.PixelFormat;
+import android.media.tv.flags.Flags;
 import android.os.Parcel;
 import android.os.Parcelable;
 
@@ -24,9 +28,11 @@ import androidx.annotation.NonNull;
 import java.util.Arrays;
 
 /**
+ * Metadata of ambient backlight.
  * @hide
  */
-public class AmbientBacklightMetadata implements Parcelable {
+@FlaggedApi(Flags.FLAG_MEDIA_QUALITY_FW)
+public final class AmbientBacklightMetadata implements Parcelable {
     @NonNull
     private final String mPackageName;
     private final int mCompressAlgorithm;
@@ -37,6 +43,9 @@ public class AmbientBacklightMetadata implements Parcelable {
     @NonNull
     private final int[] mZonesColors;
 
+    /**
+     * Constructor of AmbientBacklightMetadata.
+     */
     public AmbientBacklightMetadata(@NonNull String packageName, int compressAlgorithm,
             int source, int colorFormat, int horizontalZonesNumber, int verticalZonesNumber,
             @NonNull int[] zonesColors) {
@@ -59,31 +68,58 @@ public class AmbientBacklightMetadata implements Parcelable {
         mZonesColors = in.createIntArray();
     }
 
+    /**
+     * Gets package name.
+     * @hide
+     */
     @NonNull
     public String getPackageName() {
         return mPackageName;
     }
 
+    /**
+     * Gets compress algorithm.
+     */
+    @AmbientBacklightSettings.CompressAlgorithm
     public int getCompressAlgorithm() {
         return mCompressAlgorithm;
     }
 
+    /**
+     * Gets source of ambient backlight detection.
+     */
+    @AmbientBacklightSettings.Source
     public int getSource() {
         return mSource;
     }
 
+    /**
+     * Gets color format.
+     */
+    @PixelFormat.Format
     public int getColorFormat() {
         return mColorFormat;
     }
 
+    /**
+     * Gets the number of lights in each horizontal zone.
+     */
+    @IntRange(from = 0)
     public int getHorizontalZonesNumber() {
         return mHorizontalZonesNumber;
     }
 
+    /**
+     * Gets the number of lights in each vertical zone.
+     */
+    @IntRange(from = 0)
     public int getVerticalZonesNumber() {
         return mVerticalZonesNumber;
     }
 
+    /**
+     * @hide
+     */
     @NonNull
     public int[] getZonesColors() {
         return mZonesColors;
diff --git a/media/java/android/media/quality/AmbientBacklightSettings.java b/media/java/android/media/quality/AmbientBacklightSettings.java
index bb782bf1aee4..4ed7bc79fdca 100644
--- a/media/java/android/media/quality/AmbientBacklightSettings.java
+++ b/media/java/android/media/quality/AmbientBacklightSettings.java
@@ -16,7 +16,11 @@
 
 package android.media.quality;
 
+import android.annotation.FlaggedApi;
 import android.annotation.IntDef;
+import android.annotation.IntRange;
+import android.graphics.PixelFormat;
+import android.media.tv.flags.Flags;
 import android.os.Parcel;
 import android.os.Parcelable;
 
@@ -29,7 +33,8 @@ import java.lang.annotation.RetentionPolicy;
  * Settings for ambient backlight.
  * @hide
  */
-public class AmbientBacklightSettings implements Parcelable {
+@FlaggedApi(Flags.FLAG_MEDIA_QUALITY_FW)
+public final class AmbientBacklightSettings implements Parcelable {
     /** @hide */
     @Retention(RetentionPolicy.SOURCE)
     @IntDef({SOURCE_NONE, SOURCE_AUDIO, SOURCE_VIDEO, SOURCE_AUDIO_VIDEO})
@@ -62,6 +67,7 @@ public class AmbientBacklightSettings implements Parcelable {
 
     /**
      * The color format is RGB888.
+     * @hide
      */
     public static final int COLOR_FORMAT_RGB888 = 1;
 
@@ -76,7 +82,7 @@ public class AmbientBacklightSettings implements Parcelable {
     public static final int ALGORITHM_NONE = 0;
 
     /**
-     * The compress algorithm is RLE.
+     * The compress algorithm is run length encoding (RLE).
      */
     public static final int ALGORITHM_RLE = 1;
 
@@ -115,6 +121,9 @@ public class AmbientBacklightSettings implements Parcelable {
      */
     private final int mThreshold;
 
+    /**
+     * Constructs AmbientBacklightSettings.
+     */
     public AmbientBacklightSettings(int source, int maxFps, int colorFormat,
             int horizontalZonesNumber, int verticalZonesNumber, boolean isLetterboxOmitted,
             int threshold) {
@@ -137,32 +146,57 @@ public class AmbientBacklightSettings implements Parcelable {
         mThreshold = in.readInt();
     }
 
+    /**
+     * Gets source of ambient backlight detection.
+     */
     @Source
     public int getSource() {
         return mSource;
     }
 
+    /**
+     * Gets max frames per second.
+     */
+    @IntRange(from = 1)
     public int getMaxFps() {
         return mMaxFps;
     }
 
-    @ColorFormat
+    /**
+     * Gets color format.
+     */
+    @PixelFormat.Format
     public int getColorFormat() {
         return mColorFormat;
     }
 
+    /**
+     * Gets the number of lights in each horizontal zone.
+     */
+    @IntRange(from = 0)
     public int getHorizontalZonesNumber() {
         return mHorizontalZonesNumber;
     }
 
+    /**
+     * Gets the number of lights in each vertical zone.
+     */
+    @IntRange(from = 0)
     public int getVerticalZonesNumber() {
         return mVerticalZonesNumber;
     }
 
+    /**
+     * Returns {@code true} if letter box is omitted; {@code false} otherwise.
+     * @hide
+     */
     public boolean isLetterboxOmitted() {
         return mIsLetterboxOmitted;
     }
 
+    /**
+     * @hide
+     */
     public int getThreshold() {
         return mThreshold;
     }
diff --git a/media/java/android/media/quality/MediaQualityManager.java b/media/java/android/media/quality/MediaQualityManager.java
index 26d83aca3e7b..4d4526cf9925 100644
--- a/media/java/android/media/quality/MediaQualityManager.java
+++ b/media/java/android/media/quality/MediaQualityManager.java
@@ -567,7 +567,6 @@ public final class MediaQualityManager {
 
     /**
      * Registers a {@link AmbientBacklightCallback}.
-     * @hide
      */
     public void registerAmbientBacklightCallback(
             @NonNull @CallbackExecutor Executor executor,
@@ -581,7 +580,6 @@ public final class MediaQualityManager {
 
     /**
      * Unregisters the existing {@link AmbientBacklightCallback}.
-     * @hide
      */
     public void unregisterAmbientBacklightCallback(
             @NonNull final AmbientBacklightCallback callback) {
@@ -602,7 +600,6 @@ public final class MediaQualityManager {
      * Set the ambient backlight settings.
      *
      * @param settings The settings to use for the backlight detector.
-     * @hide
      */
     public void setAmbientBacklightSettings(
             @NonNull AmbientBacklightSettings settings) {
@@ -618,7 +615,6 @@ public final class MediaQualityManager {
      * Enables or disables the ambient backlight detection.
      *
      * @param enabled {@code true} to enable, {@code false} to disable.
-     * @hide
      */
     public void setAmbientBacklightEnabled(boolean enabled) {
         try {
@@ -843,14 +839,12 @@ public final class MediaQualityManager {
 
     /**
      * Callback used to monitor status of ambient backlight.
-     * @hide
      */
     public abstract static class AmbientBacklightCallback {
         /**
          * Called when new ambient backlight event is emitted.
-         * @hide
          */
-        public void onAmbientBacklightEvent(AmbientBacklightEvent event) {
+        public void onAmbientBacklightEvent(@NonNull AmbientBacklightEvent event) {
         }
     }
 }