DynamicRange

@RequiresApi(value = 21)
public final class DynamicRange

A representation of the dynamic range of an image.

The dynamic range specifies an encoding for how pixels will be displayed on screen along with the number of bits used to encode each pixel. In general, the encoding represents a set of operations applied to each pixel to expand the range of light and dark pixels on a specific screen. The bit depth represents the discrete number of steps those pixels can assume between the lightest and darkest pixels.

A category of dynamic ranges called high-dynamic range (HDR) are able to encode brighter highlights, darker shadows, and richer color. This class contains constants for specific HDR dynamic ranges, such as HLG_10_BIT, but also unspecified HDR dynamic ranges, such as HDR_UNSPECIFIED_10_BIT. When used with a camera API, such as setDynamicRange, these unspecified dynamic ranges will use device defaults as the HDR encoding.

The legacy behavior of most devices is to capture in standard dynamic range (SDR), which is represented by SDR. This will be the default dynamic range encoding for most APIs taking dynamic range unless otherwise specified.

See also
setDynamicRange

Summary

Constants
static final int

Ten-bit bit depth.
static final int

Eight-bit bit depth.
static final int

Bit depth is unspecified and may be determined automatically by the device.
static final @NonNull DynamicRange

A 10-bit high-dynamic range with Dolby Vision encoding.
static final @NonNull DynamicRange

An 8-bit high-dynamic range with Dolby Vision encoding.
static final int

Dolby Vision dynamic range encoding.
static final int

HDR10 dynamic range encoding.
static final int

HDR10+ dynamic range encoding.
static final int

An unspecified dynamic range encoding which allows the device to determine the underlying dynamic range encoding, limited to High Dynamic Range (HDR) encodings.
static final int

Hybrid Log Gamma (HLG) dynamic range encoding.
static final int

Standard Dynamic Range (SDR) encoding.
static final int

An unspecified dynamic range encoding which allows the device to determine the underlying dynamic range encoding.
static final @NonNull DynamicRange

A 10-bit high-dynamic range with HDR10 encoding.
static final @NonNull DynamicRange

A 10-bit high-dynamic range with HDR10+ encoding.
static final @NonNull DynamicRange

A dynamic range representing 10-bit high dynamic range (HDR) with unspecified encoding.
static final @NonNull DynamicRange

A 10-bit high-dynamic range with HLG encoding.
static final @NonNull DynamicRange

A dynamic range representing 8-bit standard dynamic range (SDR).
static final @NonNull DynamicRange

A dynamic range with unspecified encoding and bit depth.

Public constructors
DynamicRange(int encoding, int bitDepth)

Creates a dynamic range representation from a encoding and bit depth.

Public methods
boolean
int

Returns the bit depth used by this dynamic range configuration.
int

Returns the dynamic range encoding.
int
@NonNull String

Constants

BIT_DEPTH_10_BIT

Added in 1.3.0
public static final int BIT_DEPTH_10_BIT = 10

Ten-bit bit depth.

BIT_DEPTH_8_BIT

Added in 1.3.0
public static final int BIT_DEPTH_8_BIT = 8

Eight-bit bit depth.

BIT_DEPTH_UNSPECIFIED

Added in 1.3.0
public static final int BIT_DEPTH_UNSPECIFIED = 0

Bit depth is unspecified and may be determined automatically by the device.

DOLBY_VISION_10_BIT

Added in 1.3.0
public static final @NonNull DynamicRange DOLBY_VISION_10_BIT

A 10-bit high-dynamic range with Dolby Vision encoding.

This dynamic range is composed of: 

  Encoding: ENCODING_DOLBY_VISION
  Bit Depth: BIT_DEPTH_10_BIT

DOLBY_VISION_8_BIT

Added in 1.3.0
public static final @NonNull DynamicRange DOLBY_VISION_8_BIT

An 8-bit high-dynamic range with Dolby Vision encoding.

This dynamic range is composed of: 

  Encoding: ENCODING_DOLBY_VISION
  Bit Depth: BIT_DEPTH_8_BIT

ENCODING_DOLBY_VISION

Added in 1.3.0
public static final int ENCODING_DOLBY_VISION = 6

Dolby Vision dynamic range encoding.

ENCODING_HDR10

Added in 1.3.0
public static final int ENCODING_HDR10 = 4

HDR10 dynamic range encoding.

ENCODING_HDR10_PLUS

Added in 1.3.0
public static final int ENCODING_HDR10_PLUS = 5

HDR10+ dynamic range encoding.

ENCODING_HDR_UNSPECIFIED

Added in 1.3.0
public static final int ENCODING_HDR_UNSPECIFIED = 2

An unspecified dynamic range encoding which allows the device to determine the underlying dynamic range encoding, limited to High Dynamic Range (HDR) encodings.

ENCODING_HLG

Added in 1.3.0
public static final int ENCODING_HLG = 3

Hybrid Log Gamma (HLG) dynamic range encoding.

ENCODING_SDR

Added in 1.3.0
public static final int ENCODING_SDR = 1

Standard Dynamic Range (SDR) encoding.

ENCODING_UNSPECIFIED

Added in 1.3.0
public static final int ENCODING_UNSPECIFIED = 0

An unspecified dynamic range encoding which allows the device to determine the underlying dynamic range encoding.

HDR10_10_BIT

Added in 1.3.0
public static final @NonNull DynamicRange HDR10_10_BIT

A 10-bit high-dynamic range with HDR10 encoding.

This dynamic range is composed of: 

  Encoding: ENCODING_HDR10
  Bit Depth: BIT_DEPTH_10_BIT

HDR10_PLUS_10_BIT

Added in 1.3.0
public static final @NonNull DynamicRange HDR10_PLUS_10_BIT

A 10-bit high-dynamic range with HDR10+ encoding.

This dynamic range is composed of: 

  Encoding: ENCODING_HDR10_PLUS
  Bit Depth: BIT_DEPTH_10_BIT

HDR_UNSPECIFIED_10_BIT

Added in 1.3.0
public static final @NonNull DynamicRange HDR_UNSPECIFIED_10_BIT

A dynamic range representing 10-bit high dynamic range (HDR) with unspecified encoding.

The HDR encoding is unspecified, and may defer to device defaults when used to select a dynamic range. In this case, the dynamic range will be limited to 10-bit high dynamic ranges.

This dynamic range is composed of: 

  Encoding: ENCODING_HDR_UNSPECIFIED
  Bit Depth: BIT_DEPTH_10_BIT

HLG_10_BIT

Added in 1.3.0
public static final @NonNull DynamicRange HLG_10_BIT

A 10-bit high-dynamic range with HLG encoding.

This dynamic range is composed of: 

  Encoding: ENCODING_HLG
  Bit Depth: BIT_DEPTH_10_BIT

SDR

Added in 1.3.0
public static final @NonNull DynamicRange SDR

A dynamic range representing 8-bit standard dynamic range (SDR).

This dynamic range is composed of: 

  Encoding: ENCODING_SDR
  Bit Depth: BIT_DEPTH_8_BIT

UNSPECIFIED

Added in 1.3.0
public static final @NonNull DynamicRange UNSPECIFIED

A dynamic range with unspecified encoding and bit depth.

The dynamic range is unspecified and may defer to device defaults when used to select a dynamic range.

This dynamic range is composed of: 

  Encoding: ENCODING_UNSPECIFIED
  Bit Depth: BIT_DEPTH_UNSPECIFIED

Public constructors

DynamicRange

Added in 1.3.0
public DynamicRange(int encoding, int bitDepth)

Creates a dynamic range representation from a encoding and bit depth.

This constructor is left public for testing purposes. It does not do any verification that the provided arguments are a valid combination of encoding and bit depth.

Parameters
int encoding

The dynamic range encoding.
int bitDepth

The bit depth.

Public methods

equals

public boolean equals(Object o)

getBitDepth

Added in 1.3.0
public int getBitDepth()

Returns the bit depth used by this dynamic range configuration.

Common values are BIT_DEPTH_8_BIT, such as for ENCODING_SDR or BIT_DEPTH_10_BIT, such as for ENCODING_HDR10.

Returns
int

The bit depth. Possible values are BIT_DEPTH_8_BIT, BIT_DEPTH_10_BIT, or BIT_DEPTH_UNSPECIFIED.

getEncoding

Added in 1.3.0
public int getEncoding()

Returns the dynamic range encoding.

Returns
int

The dynamic range encoding. Possible values are ENCODING_SDR, ENCODING_HLG, ENCODING_HDR10, ENCODING_HDR10_PLUS, or ENCODING_DOLBY_VISION.

hashCode

public int hashCode()

toString

public @NonNull String toString()