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

Commit 2d95e8c7 authored by John Reck's avatar John Reck
Browse files

Address API feedback 

Fixes: 271426288
Test: make offline-sdk-docs & inspect
Change-Id: I3bcc189e7df35274978f5125fc141a646b85d39a
parent 8f5595eb

core/api/current.txt

+7 −7
Original line number Diff line number Diff line
@@ -15485,14 +15485,14 @@ package android.graphics { 
    method @NonNull public float getMinDisplayRatioForHdrTransition();

    method @NonNull public float[] getRatioMax();

    method @NonNull public float[] getRatioMin();

    method @NonNull public void setDisplayRatioForFullHdr(float);

    method @NonNull public void setEpsilonHdr(float, float, float);

    method @NonNull public void setEpsilonSdr(float, float, float);

    method public void setDisplayRatioForFullHdr(@FloatRange(from=1.0f) float);

    method public void setEpsilonHdr(float, float, float);

    method public void setEpsilonSdr(float, float, float);

    method public void setGainmapContents(@NonNull android.graphics.Bitmap);

    method @NonNull public void setGamma(float, float, float);

    method @NonNull public void setMinDisplayRatioForHdrTransition(@FloatRange(from=1.0f) float);

    method @NonNull public void setRatioMax(float, float, float);

    method @NonNull public void setRatioMin(float, float, float);

    method public void setGamma(float, float, float);

    method public void setMinDisplayRatioForHdrTransition(@FloatRange(from=1.0f) float);

    method public void setRatioMax(float, float, float);

    method public void setRatioMin(float, float, float);

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

    field @NonNull public static final android.os.Parcelable.Creator<android.graphics.Gainmap> CREATOR;

  }

graphics/java/android/graphics/Gainmap.java

+14 −21
Original line number Diff line number Diff line
@@ -25,13 +25,11 @@ import libcore.util.NativeAllocationRegistry; 


/**

 * Gainmap represents a mechanism for augmenting an SDR image to produce an HDR one with variable

 * display adjustment capability.

 *

 * It is a combination of a set of metadata describing how to apply the gainmap, as well as either

 * a 1 (such as {@link android.graphics.Bitmap.Config#ALPHA_8} or 3

 * display adjustment capability. It is a combination of a set of metadata describing how to apply

 * the gainmap, as well as either a 1 (such as {@link android.graphics.Bitmap.Config#ALPHA_8} or 3

 * (such as {@link android.graphics.Bitmap.Config#ARGB_8888} with the alpha channel ignored)

 * channel Bitmap that represents the gainmap data itself.

 *

 * <p>

 * When rendering to an {@link android.content.pm.ActivityInfo#COLOR_MODE_HDR} activity, the

 * hardware accelerated {@link Canvas} will automatically apply the gainmap when sufficient

 * HDR headroom is available.
@@ -45,7 +43,7 @@ import libcore.util.NativeAllocationRegistry; 
 * image, often at a lower resolution (such as 1/4th), along with some metadata to describe

 * how to apply the gainmap. The gainmap image itself is then a greyscale image representing

 * the transformation to apply onto the base image to reconstruct an HDR rendition of it.

 *

 * <p>

 * As such these "gainmap images" consist of 3 parts - a base {@link Bitmap} with a

 * {@link Bitmap#getGainmap()} that returns an instance of this class which in turn contains

 * the enhancement layer represented as another Bitmap, accessible via {@link #getGainmapContents()}
@@ -55,25 +53,27 @@ import libcore.util.NativeAllocationRegistry; 
 * When doing custom rendering such as to an OpenGL ES or Vulkan context, the gainmap is not

 * automatically applied. In such situations, the following steps are appropriate to render the

 * gainmap in combination with the base image.

 *

 * <p>

 * Suppose our display has HDR to SDR ratio of H, and we wish to display an image with gainmap on

 * this display. Let B be the pixel value from the base image in a color space that has the

 * primaries of the base image and a linear transfer function. Let G be the pixel value from the

 * gainmap. Let D be the output pixel in the same color space as B. The value of D is computed

 * as follows:

 *

 * <p>

 * First, let W be a weight parameter determining how much the gainmap will be applied.

 * <pre class="prettyprint">

 *   W = clamp((log(H)                      - log(minDisplayRatioForHdrTransition)) /

 *             (log(displayRatioForFullHdr) - log(minDisplayRatioForHdrTransition), 0, 1)

 *             (log(displayRatioForFullHdr) - log(minDisplayRatioForHdrTransition), 0, 1)</pre>

 *

 * Next, let L be the gainmap value in log space. We compute this from the value G that was

 * sampled from the texture as follows:

 *   L = mix(log(ratioMin), log(ratioMax), pow(G, gamma))

 *

 * <pre class="prettyprint">

 *   L = mix(log(ratioMin), log(ratioMax), pow(G, gamma))</pre>

 * Finally, apply the gainmap to compute D, the displayed pixel. If the base image is SDR then

 * compute:

 *   D = (B + epsilonSdr) * exp(L * W) - epsilonHdr

 *

 * <pre class="prettyprint">

 *   D = (B + epsilonSdr) * exp(L * W) - epsilonHdr</pre>

 * <p>

 * In the above math, log() is a natural logarithm and exp() is natural exponentiation. The base

 * for these functions cancels out and does not affect the result, so other bases may be used

 * if preferred.
@@ -150,7 +150,6 @@ public final class Gainmap implements Parcelable { 
    /**

     * Sets the gainmap ratio min. For single-plane gainmaps, r, g, and b should be the same.

     */

    @NonNull

    public void setRatioMin(float r, float g, float b) {

        nSetRatioMin(mNativePtr, r, g, b);

    }
@@ -169,7 +168,6 @@ public final class Gainmap implements Parcelable { 
    /**

     * Sets the gainmap ratio max. For single-plane gainmaps, r, g, and b should be the same.

     */

    @NonNull

    public void setRatioMax(float r, float g, float b) {

        nSetRatioMax(mNativePtr, r, g, b);

    }
@@ -188,7 +186,6 @@ public final class Gainmap implements Parcelable { 
    /**

     * Sets the gainmap gamma. For single-plane gainmaps, r, g, and b should be the same.

     */

    @NonNull

    public void setGamma(float r, float g, float b) {

        nSetGamma(mNativePtr, r, g, b);

    }
@@ -208,7 +205,6 @@ public final class Gainmap implements Parcelable { 
     * Sets the sdr epsilon which is used to avoid numerical instability.

     * For single-plane gainmaps, r, g, and b should be the same.

     */

    @NonNull

    public void setEpsilonSdr(float r, float g, float b) {

        nSetEpsilonSdr(mNativePtr, r, g, b);

    }
@@ -228,7 +224,6 @@ public final class Gainmap implements Parcelable { 
     * Sets the hdr epsilon which is used to avoid numerical instability.

     * For single-plane gainmaps, r, g, and b should be the same.

     */

    @NonNull

    public void setEpsilonHdr(float r, float g, float b) {

        nSetEpsilonHdr(mNativePtr, r, g, b);

    }
@@ -248,8 +243,7 @@ public final class Gainmap implements Parcelable { 
     * Sets the hdr/sdr ratio at which point the gainmap is fully applied.

     * @param max The hdr/sdr ratio at which the gainmap is fully applied. Must be >= 1.0f

     */

    @NonNull

    public void setDisplayRatioForFullHdr(float max) {

    public void setDisplayRatioForFullHdr(@FloatRange(from = 1.0f) float max) {

        if (!Float.isFinite(max) || max < 1f) {

            throw new IllegalArgumentException(

                    "setDisplayRatioForFullHdr must be >= 1.0f, got = " + max);
@@ -269,7 +263,6 @@ public final class Gainmap implements Parcelable { 
     * Sets the hdr/sdr ratio below which only the SDR image is displayed.

     * @param min The minimum hdr/sdr ratio at which to begin applying the gainmap. Must be >= 1.0f

     */

    @NonNull

    public void setMinDisplayRatioForHdrTransition(@FloatRange(from = 1.0f) float min) {

        if (!Float.isFinite(min) || min < 1f) {

            throw new IllegalArgumentException(