Donate to e Foundation | Murena handsets with /e/OS | Own a part of Murena! Learn more

Commit 0a9e3419 authored by Kenny Guy's avatar Kenny Guy
Browse files

Clarify brightness correction API 

Add annotations to clarify the brightness
correction API.

Bug: 125347154
Test: atest android.display.cts.BrightnessTest
Test: manual, flash phone, get app using API to push corrections, adb shell dumpsys display
Change-Id: Icbb61bb542a49c49f279b865d69d59a542c0e42b
parent 8e95f0bf

api/system-current.txt

+4 −4
Original line number Original line Diff line number Diff line
@@ -1894,7 +1894,7 @@ package android.hardware.display { 
  public final class BrightnessConfiguration implements android.os.Parcelable {

  public final class BrightnessConfiguration implements android.os.Parcelable {

    method public int describeContents();

    method public int describeContents();

    method @Nullable public android.hardware.display.BrightnessCorrection getCorrectionByCategory(int);

    method @Nullable public android.hardware.display.BrightnessCorrection getCorrectionByCategory(int);

    method @Nullable public android.hardware.display.BrightnessCorrection getCorrectionByPackageName(String);

    method @Nullable public android.hardware.display.BrightnessCorrection getCorrectionByPackageName(@NonNull String);

    method public android.util.Pair<float[],float[]> getCurve();

    method public android.util.Pair<float[],float[]> getCurve();

    method public void writeToParcel(android.os.Parcel, int);

    method public void writeToParcel(android.os.Parcel, int);

    field public static final android.os.Parcelable.Creator<android.hardware.display.BrightnessConfiguration> CREATOR;

    field public static final android.os.Parcelable.Creator<android.hardware.display.BrightnessConfiguration> CREATOR;
@@ -1902,8 +1902,8 @@ package android.hardware.display { 
















  public static class BrightnessConfiguration.Builder {







  public static class BrightnessConfiguration.Builder {











    ctor public BrightnessConfiguration.Builder(float[], float[]);







    ctor public BrightnessConfiguration.Builder(float[], float[]);











    method public android.hardware.display.BrightnessConfiguration.Builder addCorrectionByCategory(int, android.hardware.display.BrightnessCorrection);







    method public android.hardware.display.BrightnessConfiguration.Builder addCorrectionByCategory(int, @NonNull android.hardware.display.BrightnessCorrection);











    method public android.hardware.display.BrightnessConfiguration.Builder addCorrectionByPackageName(String, android.hardware.display.BrightnessCorrection);







    method public android.hardware.display.BrightnessConfiguration.Builder addCorrectionByPackageName(@NonNull String, @NonNull android.hardware.display.BrightnessCorrection);











    method public android.hardware.display.BrightnessConfiguration build();







    method public android.hardware.display.BrightnessConfiguration build();











    method public int getMaxCorrectionsByCategory();







    method public int getMaxCorrectionsByCategory();











    method public int getMaxCorrectionsByPackageName();







    method public int getMaxCorrectionsByPackageName();









@@ -1911,7 +1911,7 @@ package android.hardware.display {









  }







  }



























  public final class BrightnessCorrection implements android.os.Parcelable {







  public final class BrightnessCorrection implements android.os.Parcelable {











    method public float apply(float);







    method @FloatRange(from=0.0) public float apply(@FloatRange(from=0.0) float);











    method @NonNull public static android.hardware.display.BrightnessCorrection createScaleAndTranslateLog(float, float);







    method @NonNull public static android.hardware.display.BrightnessCorrection createScaleAndTranslateLog(float, float);











    method public int describeContents();







    method public int describeContents();











    method public void writeToParcel(android.os.Parcel, int);







    method public void writeToParcel(android.os.Parcel, int);

































api/test-current.txt



+4
−4




























Original line number
Original line
Diff line number
Diff line








@@ -765,7 +765,7 @@ package android.hardware.display {









  public final class BrightnessConfiguration implements android.os.Parcelable {







  public final class BrightnessConfiguration implements android.os.Parcelable {











    method public int describeContents();







    method public int describeContents();











    method @Nullable public android.hardware.display.BrightnessCorrection getCorrectionByCategory(int);







    method @Nullable public android.hardware.display.BrightnessCorrection getCorrectionByCategory(int);











    method @Nullable public android.hardware.display.BrightnessCorrection getCorrectionByPackageName(String);







    method @Nullable public android.hardware.display.BrightnessCorrection getCorrectionByPackageName(@NonNull String);











    method public android.util.Pair<float[],float[]> getCurve();







    method public android.util.Pair<float[],float[]> getCurve();











    method public void writeToParcel(android.os.Parcel, int);







    method public void writeToParcel(android.os.Parcel, int);











    field public static final android.os.Parcelable.Creator<android.hardware.display.BrightnessConfiguration> CREATOR;







    field public static final android.os.Parcelable.Creator<android.hardware.display.BrightnessConfiguration> CREATOR;









@@ -773,8 +773,8 @@ package android.hardware.display {





























  public static class BrightnessConfiguration.Builder {







  public static class BrightnessConfiguration.Builder {











    ctor public BrightnessConfiguration.Builder(float[], float[]);







    ctor public BrightnessConfiguration.Builder(float[], float[]);











    method public android.hardware.display.BrightnessConfiguration.Builder addCorrectionByCategory(int, android.hardware.display.BrightnessCorrection);







    method public android.hardware.display.BrightnessConfiguration.Builder addCorrectionByCategory(int, @NonNull android.hardware.display.BrightnessCorrection);











    method public android.hardware.display.BrightnessConfiguration.Builder addCorrectionByPackageName(String, android.hardware.display.BrightnessCorrection);







    method public android.hardware.display.BrightnessConfiguration.Builder addCorrectionByPackageName(@NonNull String, @NonNull android.hardware.display.BrightnessCorrection);











    method public android.hardware.display.BrightnessConfiguration build();







    method public android.hardware.display.BrightnessConfiguration build();











    method public int getMaxCorrectionsByCategory();







    method public int getMaxCorrectionsByCategory();











    method public int getMaxCorrectionsByPackageName();







    method public int getMaxCorrectionsByPackageName();









@@ -782,7 +782,7 @@ package android.hardware.display {









  }







  }































  public final class BrightnessCorrection implements android.os.Parcelable {







  public final class BrightnessCorrection implements android.os.Parcelable {











    method public float apply(float);







    method @FloatRange(from=0.0) public float apply(@FloatRange(from=0.0) float);











    method @NonNull public static android.hardware.display.BrightnessCorrection createScaleAndTranslateLog(float, float);







    method @NonNull public static android.hardware.display.BrightnessCorrection createScaleAndTranslateLog(float, float);











    method public int describeContents();







    method public int describeContents();











    method public void writeToParcel(android.os.Parcel, int);







    method public void writeToParcel(android.os.Parcel, int);

































core/java/android/hardware/display/BrightnessConfiguration.java



+11
−7




























Original line number
Original line
Diff line number
Diff line








@@ -16,6 +16,7 @@





























package android.hardware.display;







package android.hardware.display;


































import android.annotation.NonNull;











import android.annotation.Nullable;







import android.annotation.Nullable;











import android.annotation.SystemApi;







import android.annotation.SystemApi;











import android.annotation.TestApi;







import android.annotation.TestApi;










@@ -93,7 +94,7 @@ public final class BrightnessConfiguration implements Parcelable {









     *







     *











     */







     */











    @Nullable







    @Nullable











    public BrightnessCorrection getCorrectionByPackageName(String packageName) {







    public BrightnessCorrection getCorrectionByPackageName(@NonNull String packageName) {











        return mCorrectionsByPackageName.get(packageName);







        return mCorrectionsByPackageName.get(packageName);











    }







    }





























@@ -106,7 +107,7 @@ public final class BrightnessConfiguration implements Parcelable {









     * @return The matching brightness correction, or null.







     * @return The matching brightness correction, or null.











     */







     */











    @Nullable







    @Nullable











    public BrightnessCorrection getCorrectionByCategory(int category) {







    public BrightnessCorrection getCorrectionByCategory(@ApplicationInfo.Category int category) {











        return mCorrectionsByCategory.get(category);







        return mCorrectionsByCategory.get(category);











    }







    }






























@@ -238,7 +239,7 @@ public final class BrightnessConfiguration implements Parcelable {









     *







     *











     * @hide







     * @hide











     */







     */











    public void saveToXml(XmlSerializer serializer) throws IOException {







    public void saveToXml(@NonNull XmlSerializer serializer) throws IOException {











        serializer.startTag(null, TAG_BRIGHTNESS_CURVE);







        serializer.startTag(null, TAG_BRIGHTNESS_CURVE);











        if (mDescription != null) {







        if (mDescription != null) {











            serializer.attribute(null, ATTR_DESCRIPTION, mDescription);







            serializer.attribute(null, ATTR_DESCRIPTION, mDescription);










@@ -284,7 +285,7 @@ public final class BrightnessConfiguration implements Parcelable {









     *







     *











     * @hide







     * @hide











     */







     */











    public static BrightnessConfiguration loadFromXml(XmlPullParser parser)







    public static BrightnessConfiguration loadFromXml(@NonNull XmlPullParser parser)











            throws IOException, XmlPullParserException {







            throws IOException, XmlPullParserException {











        String description = null;







        String description = null;











        List<Float> luxList = new ArrayList<>();







        List<Float> luxList = new ArrayList<>();










@@ -443,8 +444,10 @@ public final class BrightnessConfiguration implements Parcelable {









         *      {@link #getMaxCorrectionsByPackageName}).







         *      {@link #getMaxCorrectionsByPackageName}).











         *







         *











         */







         */











        public Builder addCorrectionByPackageName(String packageName,







        public Builder addCorrectionByPackageName(@NonNull String packageName,











                BrightnessCorrection correction) {







                @NonNull BrightnessCorrection correction) {














            Objects.requireNonNull(packageName, "packageName must not be null");














            Objects.requireNonNull(correction, "correction must not be null");











            if (mCorrectionsByPackageName.size() >= getMaxCorrectionsByPackageName()) {







            if (mCorrectionsByPackageName.size() >= getMaxCorrectionsByPackageName()) {











                throw new IllegalArgumentException("Too many corrections by package name");







                throw new IllegalArgumentException("Too many corrections by package name");











            }







            }









@@ -470,7 +473,8 @@ public final class BrightnessConfiguration implements Parcelable {









         *







         *











         */







         */











        public Builder addCorrectionByCategory(@ApplicationInfo.Category int category,







        public Builder addCorrectionByCategory(@ApplicationInfo.Category int category,











                BrightnessCorrection correction) {







                @NonNull BrightnessCorrection correction) {














            Objects.requireNonNull(correction, "correction must not be null");











            if (mCorrectionsByCategory.size() >= getMaxCorrectionsByCategory()) {







            if (mCorrectionsByCategory.size() >= getMaxCorrectionsByCategory()) {











                throw new IllegalArgumentException("Too many corrections by category");







                throw new IllegalArgumentException("Too many corrections by category");











            }







            }

































core/java/android/hardware/display/BrightnessCorrection.java



+8
−6




























Original line number
Original line
Diff line number
Diff line








@@ -16,6 +16,7 @@





























package android.hardware.display;







package android.hardware.display;


































import android.annotation.FloatRange;











import android.annotation.NonNull;







import android.annotation.NonNull;











import android.annotation.SystemApi;







import android.annotation.SystemApi;











import android.annotation.TestApi;







import android.annotation.TestApi;










@@ -59,15 +60,15 @@ public final class BrightnessCorrection implements Parcelable {





























    /**







    /**











     * Creates a BrightnessCorrection that given {@code brightness}, corrects it to be







     * Creates a BrightnessCorrection that given {@code brightness}, corrects it to be











     * {@code exp(scale * log(brightness) + translate)}.







     * {@code exp(scale * ln(brightness) + translate)}.











     *







     *











     * @param scale







     * @param scale











     *      How much to scale the log brightness.







     *      How much to scale the log (base e) brightness.











     * @param translate







     * @param translate











     *      How much to translate the log brightness.







     *      How much to translate the log (base e) brightness.











     *







     *











     * @return A BrightnessCorrection that given {@code brightness}, corrects it to be







     * @return A BrightnessCorrection that given {@code brightness}, corrects it to be











     * {@code exp(scale * log(brightness) + translate)}.







     * {@code exp(scale * ln(brightness) + translate)}.











     *







     *











     * @throws IllegalArgumentException







     * @throws IllegalArgumentException











     *      - scale or translate are NaN.







     *      - scale or translate are NaN.









@@ -87,7 +88,8 @@ public final class BrightnessCorrection implements Parcelable {









     *







     *











     * @return The corrected brightness.







     * @return The corrected brightness.











     */







     */











    public float apply(float brightness) {







    @FloatRange(from = 0.0)














    public float apply(@FloatRange(from = 0.0) float brightness) {











        return mImplementation.apply(brightness);







        return mImplementation.apply(brightness);











    }







    }






























@@ -202,7 +204,7 @@ public final class BrightnessCorrection implements Parcelable {





























    /**







    /**











     * A BrightnessCorrection that given {@code brightness}, corrects it to be







     * A BrightnessCorrection that given {@code brightness}, corrects it to be











     * {@code exp(scale * log(brightness) + translate)}.







     * {@code exp(scale * ln(brightness) + translate)}.











     */







     */











    private static class ScaleAndTranslateLog implements BrightnessCorrectionImplementation {







    private static class ScaleAndTranslateLog implements BrightnessCorrectionImplementation {











        private static final float MIN_SCALE = 0.5f;







        private static final float MIN_SCALE = 0.5f;