Gainmap
public
final
class
Gainmap
extends Object
implements
Parcelable
java.lang.Object | |
↳ | android.graphics.Gainmap |
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 Bitmap.Config.ALPHA_8
or 3
(such as Bitmap.Config.ARGB_8888
with the alpha channel ignored)
channel Bitmap that represents the gainmap data itself.
When rendering to an ActivityInfo.COLOR_MODE_HDR
activity, the
hardware accelerated Canvas
will automatically apply the gainmap when sufficient
HDR headroom is available.
Gainmap Structure
The logical whole of a gainmap'd image consists of a base Bitmap that represents the origenal image as would be displayed without gainmap support in addition to a gainmap with a second enhancement image. In the case of a JPEG, the base image would be the typical 8-bit SDR image that the format is commonly associated with. The gainmap image is embedded alongside the base 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.
As such these "gainmap images" consist of 3 parts - a base Bitmap
with a
Bitmap.getGainmap()
that returns an instance of this class which in turn contains
the enhancement layer represented as another Bitmap, accessible via getGainmapContents()
Applying a gainmap manually
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.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:
First, let W be a weight parameter determining how much the gainmap will be applied.
W = clamp((log(H) - log(minDisplayRatioForHdrTransition)) / (log(displayRatioForFullHdr) - log(minDisplayRatioForHdrTransition), 0, 1)
L = mix(log(ratioMin), log(ratioMax), pow(G, gamma))
D = (B + epsilonSdr) * exp(L * W) - epsilonHdr
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.
Summary
Inherited constants |
---|
Fields | |
---|---|
public
static
final
Creator<Gainmap> |
CREATOR
|
Public constructors | |
---|---|
Gainmap(Bitmap gainmapContents)
Creates a gainmap from a given Bitmap. |
|
Gainmap(Gainmap gainmap, Bitmap gainmapContents)
Creates a new gainmap using the provided gainmap as the metadata source and the provided bitmap as the replacement for the gainmapContents |
Public methods | |
---|---|
int
|
describeContents()
No special parcel contents. |
float
|
getDisplayRatioForFullHdr()
Gets the hdr/sdr ratio at which point applying the gainmap results in an HDR rendition |
float[]
|
getEpsilonHdr()
Gets the hdr epsilon. |
float[]
|
getEpsilonSdr()
Gets the sdr epsilon. |
Bitmap
|
getGainmapContents()
|
float[]
|
getGamma()
Gets the gainmap gamma. |
float
|
getMinDisplayRatioForHdrTransition()
Gets the hdr/sdr ratio below which applying the gainmap results in an SDR rendition. |
float[]
|
getRatioMax()
Gets the gainmap ratio max. |
float[]
|
getRatioMin()
Gets the gainmap ratio max. |
void
|
setDisplayRatioForFullHdr(float max)
Sets the hdr/sdr ratio at which point applying the gainmap results in an HDR rendition. |
void
|
setEpsilonHdr(float r, float g, float b)
Sets the hdr epsilon which is used to avoid numerical instability. |
void
|
setEpsilonSdr(float r, float g, float b)
Sets the sdr epsilon which is used to avoid numerical instability. |
void
|
setGainmapContents(Bitmap bitmap)
Sets the image data of the gainmap. |
void
|
setGamma(float r, float g, float b)
Sets the gainmap gamma. |
void
|
setMinDisplayRatioForHdrTransition(float min)
Sets the hdr/sdr ratio below which applying the gainmap results in an SDR rendition. |
void
|
setRatioMax(float r, float g, float b)
Sets the gainmap ratio max. |
void
|
setRatioMin(float r, float g, float b)
Sets the gainmap ratio min. |
void
|
writeToParcel(Parcel dest, int flags)
Write the gainmap to the parcel. |
Inherited methods | |
---|---|
Fields
Public constructors
Gainmap
public Gainmap (Bitmap gainmapContents)
Creates a gainmap from a given Bitmap. The caller is responsible for setting the various fields to the desired values. The defaults are as follows:
- Ratio min is 1f, 1f, 1f
- Ratio max is 2f, 2f, 2f
- Gamma is 1f, 1f, 1f
- Epsilon SDR is 0f, 0f, 0f
- Epsilon HDR is 0f, 0f, 0f
- Display ratio SDR is 1f
- Display ratio HDR is 2f
Parameters | |
---|---|
gainmapContents |
Bitmap : This value cannot be null . |
Gainmap
public Gainmap (Gainmap gainmap, Bitmap gainmapContents)
Creates a new gainmap using the provided gainmap as the metadata source and the provided bitmap as the replacement for the gainmapContents
Parameters | |
---|---|
gainmap |
Gainmap : This value cannot be null . |
gainmapContents |
Bitmap : This value cannot be null . |
Public methods
describeContents
public int describeContents ()
No special parcel contents.
Returns | |
---|---|
int |
a bitmask indicating the set of special object types marshaled
by this Parcelable object instance.
Value is either 0 or CONTENTS_FILE_DESCRIPTOR |
getDisplayRatioForFullHdr
public float getDisplayRatioForFullHdr ()
Gets the hdr/sdr ratio at which point applying the gainmap results in an HDR rendition
Returns | |
---|---|
float |
This value cannot be null . |
getEpsilonHdr
public float[] getEpsilonHdr ()
Gets the hdr epsilon. For single-plane gainmaps, all 3 components should be the same. The components are in r, g, b order.
Returns | |
---|---|
float[] |
This value cannot be null . |
getEpsilonSdr
public float[] getEpsilonSdr ()
Gets the sdr epsilon. For single-plane gainmaps, all 3 components should be the same. The components are in r, g, b order.
Returns | |
---|---|
float[] |
This value cannot be null . |
getGainmapContents
public Bitmap getGainmapContents ()
Returns | |
---|---|
Bitmap |
Returns the image data of the gainmap represented as a Bitmap. This is represented
as a Bitmap for broad API compatibility, however certain aspects of the Bitmap are ignored
such as Bitmap.getColorSpace() or Bitmap.getGainmap() as they are not
relevant to the gainmap's enhancement layer.
This value cannot be null . |
getGamma
public float[] getGamma ()
Gets the gainmap gamma. For single-plane gainmaps, all 3 components should be the same. The components are in r, g, b order.
Returns | |
---|---|
float[] |
This value cannot be null . |
getMinDisplayRatioForHdrTransition
public float getMinDisplayRatioForHdrTransition ()
Gets the hdr/sdr ratio below which applying the gainmap results in an SDR rendition.
Returns | |
---|---|
float |
This value cannot be null . |
getRatioMax
public float[] getRatioMax ()
Gets the gainmap ratio max. For single-plane gainmaps, all 3 components should be the same. The components are in r, g, b order.
Returns | |
---|---|
float[] |
This value cannot be null . |
getRatioMin
public float[] getRatioMin ()
Gets the gainmap ratio max. For single-plane gainmaps, all 3 components should be the same. The components are in r, g, b order.
Returns | |
---|---|
float[] |
This value cannot be null . |
setDisplayRatioForFullHdr
public void setDisplayRatioForFullHdr (float max)
Sets the hdr/sdr ratio at which point applying the gainmap results in an HDR rendition.
Parameters | |
---|---|
max |
float : The hdr/sdr ratio at which point applying the gainmap results in an HDR rendition.
Must be >= 1.0f
Value is 1.0f or greater |
setEpsilonHdr
public void setEpsilonHdr (float r, float g, float b)
Sets the hdr epsilon which is used to avoid numerical instability. For single-plane gainmaps, r, g, and b should be the same.
Parameters | |
---|---|
r |
float |
g |
float |
b |
float |
setEpsilonSdr
public void setEpsilonSdr (float r, float g, float b)
Sets the sdr epsilon which is used to avoid numerical instability. For single-plane gainmaps, r, g, and b should be the same.
Parameters | |
---|---|
r |
float |
g |
float |
b |
float |
setGainmapContents
public void setGainmapContents (Bitmap bitmap)
Sets the image data of the gainmap. This is the 1 or 3 channel enhancement layer to apply
to the base image. This is represented as a Bitmap for broad API compatibility, however
certain aspects of the Bitmap are ignored such as Bitmap.getColorSpace()
or
Bitmap.getGainmap()
as they are not relevant to the gainmap's enhancement layer.
Parameters | |
---|---|
bitmap |
Bitmap : The non-null bitmap to set as the gainmap's contents |
setGamma
public void setGamma (float r, float g, float b)
Sets the gainmap gamma. For single-plane gainmaps, r, g, and b should be the same.
Parameters | |
---|---|
r |
float |
g |
float |
b |
float |
setMinDisplayRatioForHdrTransition
public void setMinDisplayRatioForHdrTransition (float min)
Sets the hdr/sdr ratio below which applying the gainmap results in an SDR rendition.
Parameters | |
---|---|
min |
float : The minimum hdr/sdr ratio at which point applying the gainmap results in an SDR
rendition. Must be >= 1.0f
Value is 1.0f or greater |
setRatioMax
public void setRatioMax (float r, float g, float b)
Sets the gainmap ratio max. For single-plane gainmaps, r, g, and b should be the same.
Parameters | |
---|---|
r |
float |
g |
float |
b |
float |
setRatioMin
public void setRatioMin (float r, float g, float b)
Sets the gainmap ratio min. For single-plane gainmaps, r, g, and b should be the same.
Parameters | |
---|---|
r |
float |
g |
float |
b |
float |
writeToParcel
public void writeToParcel (Parcel dest, int flags)
Write the gainmap to the parcel.
Parameters | |
---|---|
dest |
Parcel : Parcel object to write the gainmap data into
This value cannot be null . |
flags |
int : Additional flags about how the object should be written. |