Merge "Fix color sampling API per review comments."

2 files changed, 21 insertions, 10 deletions

diff --git a/core/java/android/hardware/display/BrightnessChangeEvent.java b/core/java/android/hardware/display/BrightnessChangeEvent.java
index 7fa1cfb7438e..21fcc63c76fb 100644
--- a/core/java/android/hardware/display/BrightnessChangeEvent.java
+++ b/core/java/android/hardware/display/BrightnessChangeEvent.java
@@ -80,15 +80,23 @@ public final class BrightnessChangeEvent implements Parcelable {
      * Histogram counting how many times a pixel of a given value was displayed onscreen for the
      * Value component of HSV if the device supports color sampling, if the device does not support
      * color sampling the value will be null.
+     *
      * The buckets of the histogram are evenly weighted, the number of buckets is device specific.
-     * For example if we had {10, 6, 4, 1} this means that 10 pixels were in the range
-     * [0x00,0x3f], 6 pixels were in the range [0x40,0x7f] etc.
+     * The units are in pixels * milliseconds, with 1 pixel millisecond being 1 pixel displayed
+     * for 1 millisecond.
+     * For example if we had {100, 50, 30, 20}, value component was onscreen for 100 pixel
+     * milliseconds in range 0x00->0x3F, 30 pixel milliseconds in range 0x40->0x7F, etc.
+     *
+     * {@see #colorSampleDuration}
      */
     @Nullable
     public final long[] colorValueBuckets;
 
     /**
-     * How many milliseconds of data are contained in the colorValueBuckets.
+     * How many milliseconds of data are contained in the colorValueBuckets, if the device does
+     * not support color sampling the value will be 0L.
+     *
+     * {@see #colorValueBuckets}
      */
     public final long colorSampleDuration;
 
@@ -283,7 +291,8 @@ public final class BrightnessChangeEvent implements Parcelable {
             return this;
         }
 
-        /** {@see BrightnessChangeEvent#valueBuckets} */
+        /** {@see BrightnessChangeEvent#colorValueBuckets}
+         *  {@see BrightnessChangeEvent#colorSampleDuration} */
         public Builder setColorValues(@NonNull long[] colorValueBuckets, long colorSampleDuration) {
             Objects.requireNonNull(colorValueBuckets);
             mColorValueBuckets = colorValueBuckets;
diff --git a/core/java/android/hardware/display/DisplayedContentSample.java b/core/java/android/hardware/display/DisplayedContentSample.java
index 0610377c648a..4a429bb33fcb 100644
--- a/core/java/android/hardware/display/DisplayedContentSample.java
+++ b/core/java/android/hardware/display/DisplayedContentSample.java
@@ -30,12 +30,14 @@ public final class DisplayedContentSample {
      * Construct an object representing a color histogram of pixels that were displayed on screen.
      *
      * @param numFrames The number of frames represented by this sample.
-     * @param mSamplesComponent0 is a histogram counting how many times a pixel of a given value
-     * was displayed onscreen for FORMAT_COMPONENT_0. The buckets of the histogram are evenly
-     * weighted, the number of buckets is device specific.
-     * eg, for RGBA_8888, if sampleComponent0 is {10, 6, 4, 1} this means that 10 red pixels were
-     * displayed onscreen in range 0x00->0x3F, 6 red pixels were displayed onscreen in range
-     * 0x40->0x7F, etc.
+     * @param mSamplesComponent0 is a histogram counting how many times and for how long a pixel
+     * of a given value was displayed onscreen for FORMAT_COMPONENT_0. The buckets of the
+     * histogram are evenly weighted, the number of buckets is device specific.
+     * The units are in pixels * milliseconds, with 1 pixel millisecond being 1 pixel displayed
+     * onscreen for 1ms.
+     * eg, for RGBA_8888, if sampleComponent0 is {100, 50, 30, 20},  then red component was
+     * onscreen for 100 pixel milliseconds in range 0x00->0x3F, 30 pixel milliseconds in
+     * range 0x40->0x7F, etc.
      * @param mSamplesComponent1 is the same sample definition as sampleComponent0, but for the
      * second component of format.
      * @param mSamplesComponent2 is the same sample definition as sampleComponent0, but for the