DataSpace

Artifact: androidx.graphics:graphics-core

Added in 1.0.4

Kotlin |Java

public final class DataSpace

DataSpace identifies three components of colors - standard (primaries), transfer and range. A DataSpace describes how buffer data, such as from an Image or a HardwareBuffer should be interpreted by both applications and typical hardware. As buffer information is not guaranteed to be representative of color information, while DataSpace is typically used to describe three aspects of interpreting colors, some DataSpaces may describe other typical interpretations of buffer data such as depth information. Note that while ColorSpace and DataSpace are similar concepts, they are not equivalent. Not all ColorSpaces, such as ColorSpace.Named.ACES, are able to be understood by typical hardware blocks so they cannot be DataSpaces. Standard aspect Defines the chromaticity coordinates of the source primaries in terms of the CIE 1931 definition of x and y specified in ISO 11664-1. Transfer aspect Transfer characteristics are the opto-electronic transfer characteristic at the source as a function of linear optical intensity (luminance). For digital signals, E corresponds to the recorded value. Normally, the transfer function is applied in RGB space to each of the R, G and B components independently. This may result in color shift that can be minized by applying the transfer function in Lab space only for the L component. Implementation may apply the transfer function in RGB space for all pixel formats if desired. Range aspect Defines the range of values corresponding to the unit range of 0-1.

Summary

Constants
`static final int`	`DATASPACE_ADOBE_RGB = 151715840` Adobe RGB
`static final int`	`DATASPACE_BT2020 = 147193856` ITU-R Recommendation 2020 (BT.2020)
`static final int`	`DATASPACE_BT2020_HLG = 168165376` Hybrid Log Gamma encoding.
`static final int`	`DATASPACE_BT2020_PQ = 163971072` ITU-R Recommendation 2020 (BT.2020)
`static final int`	`DATASPACE_BT601_525 = 281280512` ITU-R Recommendation 709 (BT.709)
`static final int`	`DATASPACE_BT601_625 = 281149440` ITU-R Recommendation 601 (BT.601) - 525-line
`static final int`	`DATASPACE_BT709 = 281083904` ITU-R Recommendation 709 (BT.709)
`static final int`	`DATASPACE_DCI_P3 = 155844608` SMPTE EG 432-1 and SMPTE RP 431-2.
`static final int`	`DATASPACE_DEPTH = 4096` Depth.
`static final int`	`DATASPACE_DISPLAY_P3 = 143261696` Display P3
`static final int`	`DATASPACE_DYNAMIC_DEPTH = 4098` ISO 16684-1:2011(E) Dynamic Depth.
`static final int`	`DATASPACE_HEIF = 4100` High Efficiency Image File Format (HEIF).
`static final int`	`DATASPACE_JFIF = 146931712` JPEG File Interchange Format (JFIF).
`static final int`	`DATASPACE_JPEG_R = 4101` ISO/IEC TBD
`static final int`	`DATASPACE_SCRGB = 411107328` scRGB:
`static final int`	`DATASPACE_SCRGB_LINEAR = 406913024` scRGB linear encoding:
`static final int`	`DATASPACE_SRGB = 142671872` sRGB gamma encoding:
`static final int`	`DATASPACE_SRGB_LINEAR = 138477568` sRGB linear encoding:
`static final int`	`DATASPACE_UNKNOWN = 0` Default-assumption data space, when not explicitly specified.
`static final int`	`RANGE_EXTENDED` Extended range can be used in combination with FP16 to communicate scRGB or with `SurfaceControlCompat.Transaction.setExtendedRangeBrightness` to indicate an HDR range.
`static final int`	`RANGE_FULL` Full range uses all values for Y, Cb and Cr from `0` to `2^b-1`, where b is the bit depth of the color format.
`static final int`	`RANGE_LIMITED` Limited range uses values `16/2562^b` to `235/2562^b` for Y, and `1/162^b` to `15/162^b` for Cb, Cr, R, G and B, where b is the bit depth of the color format.
`static final int`	`RANGE_UNSPECIFIED` Range characteristics are unknown or are determined by the application.

Constants

DATASPACE_ADOBE_RGB

public static final int DATASPACE_ADOBE_RGB = 151715840

Adobe RGB

Use full range, gamma 2.2 transfer and Adobe RGB primaries Note: Application is responsible for gamma encoding the data as a 2.2 gamma encoding is not supported in HW.

DATASPACE_BT2020

public static final int DATASPACE_BT2020 = 147193856

ITU-R Recommendation 2020 (BT.2020)

Ultra High-definition television

Use full range, BT.709 transfer and BT2020 standard

DATASPACE_BT2020_HLG

public static final int DATASPACE_BT2020_HLG = 168165376

Hybrid Log Gamma encoding.

Composed of the following -

Primaries: STANDARD_BT2020
Transfer: TRANSFER_HLG
Range: RANGE_FULL

DATASPACE_BT2020_PQ

public static final int DATASPACE_BT2020_PQ = 163971072

ITU-R Recommendation 2020 (BT.2020)

Ultra High-definition television

Use full range, SMPTE 2084 (PQ) transfer and BT2020 standard

DATASPACE_BT601_525

public static final int DATASPACE_BT601_525 = 281280512

ITU-R Recommendation 709 (BT.709)

High-definition television.

Composed of the following -

Primaries: STANDARD_BT601_525
Transfer: TRANSFER_SMPTE_170M
Range: RANGE_LIMITED

DATASPACE_BT601_625

public static final int DATASPACE_BT601_625 = 281149440

ITU-R Recommendation 601 (BT.601) - 525-line

Standard-definition television, 525 Lines (NTSC).

Composed of the following -

Primaries: STANDARD_BT601_625
Transfer: TRANSFER_SMPTE_170M
Range: RANGE_LIMITED

DATASPACE_BT709

public static final int DATASPACE_BT709 = 281083904

ITU-R Recommendation 709 (BT.709)

High-definition television

Use limited range, BT.709 transfer and BT.709 standard.

DATASPACE_DCI_P3

public static final int DATASPACE_DCI_P3 = 155844608

SMPTE EG 432-1 and SMPTE RP 431-2.

Digital Cinema DCI-P3

Use full range, gamma 2.6 transfer and D65 DCI-P3 standard Note: Application is responsible for gamma encoding the data as a 2.6 gamma encoding is not supported in HW.

DATASPACE_DEPTH

public static final int DATASPACE_DEPTH = 4096

Depth.

This value is valid with formats HAL_PIXEL_FORMAT_Y16 and HAL_PIXEL_FORMAT_BLOB.

DATASPACE_DISPLAY_P3

public static final int DATASPACE_DISPLAY_P3 = 143261696

Display P3

Use same primaries and white-point as DCI-P3 but sRGB transfer function.

DATASPACE_DYNAMIC_DEPTH

public static final int DATASPACE_DYNAMIC_DEPTH = 4098

ISO 16684-1:2011(E) Dynamic Depth.

Embedded depth metadata following the dynamic depth specification.

DATASPACE_HEIF

public static final int DATASPACE_HEIF = 4100

High Efficiency Image File Format (HEIF).

This value is valid with HardwareBuffer.BLOB format. The combination is an HEIC image encoded by HEIC or HEVC encoder according to ISO/IEC 23008-12.

DATASPACE_JFIF

public static final int DATASPACE_JFIF = 146931712

JPEG File Interchange Format (JFIF).

Composed of the following -

Primaries: STANDARD_BT601_625
Transfer: TRANSFER_SMPTE_170M
Range: RANGE_FULL

Same model as BT.601-625, but all values (Y, Cb, Cr) range from 0 to 255

DATASPACE_JPEG_R

public static final int DATASPACE_JPEG_R = 4101

ISO/IEC TBD

JPEG image with embedded recovery map following the Jpeg/R specification.

This value must always remain aligned with the public ImageFormat Jpeg/R definition and is valid with formats: HAL_PIXEL_FORMAT_BLOB: JPEG image encoded by Jpeg/R encoder according to ISO/IEC TBD. The image contains a standard SDR JPEG and a recovery map. Jpeg/R decoders can use the map to recover the input image.

DATASPACE_SCRGB

public static final int DATASPACE_SCRGB = 411107328

scRGB:

The red, green, and blue components are stored in extended sRGB space, and gamma-encoded using the SRGB transfer function. The RGB primaries and the white point are the same as BT.709.

The values are floating point. A pixel value of 1.0, 1.0, 1.0 corresponds to sRGB white (D65) at 80 nits. Values beyond the range 0.0 - 1.0 would correspond to other colors spaces and/or HDR content.

DATASPACE_SCRGB_LINEAR

public static final int DATASPACE_SCRGB_LINEAR = 406913024

scRGB linear encoding:

The red, green, and blue components are stored in extended sRGB space, but are linear, not gamma-encoded. The RGB primaries and the white point are the same as BT.709.

The values are floating point. A pixel value of 1.0, 1.0, 1.0 corresponds to sRGB white (D65) at 80 nits. Values beyond the range 0.0 - 1.0 would correspond to other colors spaces and/or HDR content.

DATASPACE_SRGB

public static final int DATASPACE_SRGB = 142671872

sRGB gamma encoding:

The red, green and blue components are stored in sRGB space, and converted to linear space when read, using the SRGB transfer function for each of the R, G and B components. When written, the inverse transformation is performed.

The alpha component, if present, is always stored in linear space and is left unmodified when read or written.

Use full range and BT.709 standard.

DATASPACE_SRGB_LINEAR

public static final int DATASPACE_SRGB_LINEAR = 138477568

sRGB linear encoding:

The red, green, and blue components are stored in sRGB space, but are linear, not gamma-encoded. The RGB primaries and the white point are the same as BT.709.

The values are encoded using the full range (0,255 for 8-bit) for all components.

DATASPACE_UNKNOWN

public static final int DATASPACE_UNKNOWN = 0

Default-assumption data space, when not explicitly specified.

It is safest to assume the buffer is an image with sRGB primaries and encoding ranges, but the consumer and/or the producer of the data may simply be using defaults. No automatic gamma transform should be expected, except for a possible display gamma transform when drawn to a screen.

RANGE_EXTENDED

public static final int RANGE_EXTENDED

Extended range can be used in combination with FP16 to communicate scRGB or with SurfaceControlCompat.Transaction.setExtendedRangeBrightness to indicate an HDR range.

When used with floating point pixel formats and #STANDARD_BT709 then 0.0 - 1.0 is the standard sRGB space and values outside the range 0.0 - 1.0 can encode color outside the sRGB gamut. -0.5, 7.5 is the standard scRGB range. Used to blend/merge multiple dataspaces on a single display.

As of android.os.Build.VERSION_CODES.UPSIDE_DOWN_CAKE this may be combined with SurfaceControlCompat.Transaction.setExtendedRangeBrightness and other formats such as HardwareBuffer.RGBA_8888 or HardwareBuffer.RGBA_1010102 to communicate a variable HDR brightness range

RANGE_FULL

public static final int RANGE_FULL

Full range uses all values for Y, Cb and Cr from 0 to 2^b-1, where b is the bit depth of the color format.

RANGE_LIMITED

public static final int RANGE_LIMITED

Limited range uses values 16/256*2^b to 235/256*2^b for Y, and 1/16*2^b to 15/16*2^b for Cb, Cr, R, G and B, where b is the bit depth of the color format.

E.g. For 8-bit-depth formats: Luma (Y) samples should range from 16 to 235, inclusive Chroma (Cb, Cr) samples should range from 16 to 240, inclusive

For 10-bit-depth formats: Luma (Y) samples should range from 64 to 940, inclusive Chroma (Cb, Cr) samples should range from 64 to 960, inclusive.

RANGE_UNSPECIFIED

public static final int RANGE_UNSPECIFIED

Range characteristics are unknown or are determined by the application.