1 /* 2 * Copyright 2023 The Android Open Source Project 3 * 4 * Licensed under the Apache License, Version 2.0 (the "License"); 5 * you may not use this file except in compliance with the License. 6 * You may obtain a copy of the License at 7 * 8 * http://www.apache.org/licenses/LICENSE-2.0 9 * 10 * Unless required by applicable law or agreed to in writing, software 11 * distributed under the License is distributed on an "AS IS" BASIS, 12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 13 * See the License for the specific language governing permissions and 14 * limitations under the License. 15 */ 16 17 package androidx.hardware 18 19 import android.hardware.HardwareBuffer 20 import androidx.annotation.IntDef 21 import androidx.annotation.RestrictTo 22 import androidx.graphics.surface.SurfaceControlCompat 23 24 /** 25 * DataSpace identifies three components of colors - standard (primaries), transfer and range. A 26 * DataSpace describes how buffer data, such as from an Image or a HardwareBuffer should be 27 * interpreted by both applications and typical hardware. As buffer information is not guaranteed to 28 * be representative of color information, while DataSpace is typically used to describe three 29 * aspects of interpreting colors, some DataSpaces may describe other typical interpretations of 30 * buffer data such as depth information. Note that while ColorSpace and DataSpace are similar 31 * concepts, they are not equivalent. Not all ColorSpaces, such as ColorSpace.Named.ACES, are able 32 * to be understood by typical hardware blocks so they cannot be DataSpaces. Standard aspect Defines 33 * the chromaticity coordinates of the source primaries in terms of the CIE 1931 definition of x and 34 * y specified in ISO 11664-1. Transfer aspect Transfer characteristics are the opto-electronic 35 * transfer characteristic at the source as a function of linear optical intensity (luminance). For 36 * digital signals, E corresponds to the recorded value. Normally, the transfer function is applied 37 * in RGB space to each of the R, G and B components independently. This may result in color shift 38 * that can be minized by applying the transfer function in Lab space only for the L component. 39 * Implementation may apply the transfer function in RGB space for all pixel formats if desired. 40 * Range aspect Defines the range of values corresponding to the unit range of 0-1. 41 */ 42 class DataSpace private constructor() { 43 44 @RestrictTo(RestrictTo.Scope.LIBRARY) 45 @Retention(AnnotationRetention.SOURCE) 46 @IntDef( 47 flag = true, 48 value = 49 [ 50 DATASPACE_DEPTH, 51 DATASPACE_DYNAMIC_DEPTH, 52 DATASPACE_HEIF, 53 DATASPACE_JPEG_R, 54 DATASPACE_UNKNOWN, 55 DATASPACE_SCRGB_LINEAR, 56 DATASPACE_SRGB, 57 DATASPACE_SCRGB, 58 DATASPACE_DISPLAY_P3, 59 DATASPACE_BT2020_HLG, 60 DATASPACE_BT2020_PQ, 61 DATASPACE_ADOBE_RGB, 62 DATASPACE_JFIF, 63 DATASPACE_BT601_625, 64 DATASPACE_BT601_525, 65 DATASPACE_BT2020, 66 DATASPACE_BT709, 67 DATASPACE_DCI_P3, 68 DATASPACE_SRGB_LINEAR 69 ] 70 ) 71 annotation class NamedDataSpace 72 73 @RestrictTo(RestrictTo.Scope.LIBRARY) 74 @Retention(AnnotationRetention.SOURCE) 75 @IntDef(flag = true, value = [RANGE_UNSPECIFIED, RANGE_FULL, RANGE_LIMITED, RANGE_EXTENDED]) 76 annotation class DataSpaceRange 77 78 companion object { 79 80 /** 81 * Default-assumption data space, when not explicitly specified. 82 * 83 * It is safest to assume the buffer is an image with sRGB primaries and encoding ranges, 84 * but the consumer and/or the producer of the data may simply be using defaults. No 85 * automatic gamma transform should be expected, except for a possible display gamma 86 * transform when drawn to a screen. 87 */ 88 const val DATASPACE_UNKNOWN = 0 89 90 /** 91 * scRGB linear encoding: 92 * 93 * The red, green, and blue components are stored in extended sRGB space, but are linear, 94 * not gamma-encoded. The RGB primaries and the white point are the same as BT.709. 95 * 96 * The values are floating point. A pixel value of 1.0, 1.0, 1.0 corresponds to sRGB white 97 * (D65) at 80 nits. Values beyond the range [0.0 - 1.0] would correspond to other colors 98 * spaces and/or HDR content. 99 */ 100 // STANDARD_BT709 | TRANSFER_LINEAR | RANGE_EXTENDED 101 const val DATASPACE_SCRGB_LINEAR = 406913024 102 103 /** 104 * sRGB gamma encoding: 105 * 106 * The red, green and blue components are stored in sRGB space, and converted to linear 107 * space when read, using the SRGB transfer function for each of the R, G and B components. 108 * When written, the inverse transformation is performed. 109 * 110 * The alpha component, if present, is always stored in linear space and is left unmodified 111 * when read or written. 112 * 113 * Use full range and BT.709 standard. 114 */ 115 const val DATASPACE_SRGB = 142671872 // STANDARD_BT709 | TRANSFER_SRGB | RANGE_FULL 116 117 /** 118 * scRGB: 119 * 120 * The red, green, and blue components are stored in extended sRGB space, and gamma-encoded 121 * using the SRGB transfer function. The RGB primaries and the white point are the same as 122 * BT.709. 123 * 124 * The values are floating point. A pixel value of 1.0, 1.0, 1.0 corresponds to sRGB white 125 * (D65) at 80 nits. Values beyond the range [0.0 - 1.0] would correspond to other colors 126 * spaces and/or HDR content. 127 */ 128 const val DATASPACE_SCRGB = 411107328 // STANDARD_BT709 | TRANSFER_SRGB | RANGE_EXTENDED 129 130 /** 131 * Display P3 132 * 133 * Use same primaries and white-point as DCI-P3 but sRGB transfer function. 134 */ 135 const val DATASPACE_DISPLAY_P3 = 143261696 // STANDARD_DCI_P3 | TRANSFER_SRGB | RANGE_FULL 136 137 /** 138 * ITU-R Recommendation 2020 (BT.2020) 139 * 140 * Ultra High-definition television 141 * 142 * Use full range, SMPTE 2084 (PQ) transfer and BT2020 standard 143 */ 144 const val DATASPACE_BT2020_PQ = 163971072 // STANDARD_BT2020 | TRANSFER_ST2084 | RANGE_FULL 145 146 /** 147 * Adobe RGB 148 * 149 * Use full range, gamma 2.2 transfer and Adobe RGB primaries Note: Application is 150 * responsible for gamma encoding the data as a 2.2 gamma encoding is not supported in HW. 151 */ 152 // STANDARD_ADOBE_RGB | TRANSFER_GAMMA2_2 | RANGE_FULL 153 const val DATASPACE_ADOBE_RGB = 151715840 154 155 /** 156 * ITU-R Recommendation 2020 (BT.2020) 157 * 158 * Ultra High-definition television 159 * 160 * Use full range, BT.709 transfer and BT2020 standard 161 */ 162 // STANDARD_BT2020 | TRANSFER_SMPTE_170M | RANGE_FULL 163 const val DATASPACE_BT2020 = 147193856 164 165 /** 166 * ITU-R Recommendation 709 (BT.709) 167 * 168 * High-definition television 169 * 170 * Use limited range, BT.709 transfer and BT.709 standard. 171 */ 172 // STANDARD_BT709 | TRANSFER_SMPTE_170M | RANGE_LIMITED 173 const val DATASPACE_BT709 = 281083904 174 175 /** 176 * SMPTE EG 432-1 and SMPTE RP 431-2. 177 * 178 * Digital Cinema DCI-P3 179 * 180 * Use full range, gamma 2.6 transfer and D65 DCI-P3 standard Note: Application is 181 * responsible for gamma encoding the data as a 2.6 gamma encoding is not supported in HW. 182 */ 183 // STANDARD_DCI_P3 | TRANSFER_GAMMA2_6 | RANGE_FULL 184 const val DATASPACE_DCI_P3 = 155844608 185 186 /** 187 * sRGB linear encoding: 188 * 189 * The red, green, and blue components are stored in sRGB space, but are linear, not 190 * gamma-encoded. The RGB primaries and the white point are the same as BT.709. 191 * 192 * The values are encoded using the full range ([0,255] for 8-bit) for all components. 193 */ 194 // STANDARD_BT709 | TRANSFER_LINEAR | RANGE_FULL 195 const val DATASPACE_SRGB_LINEAR = 138477568 196 197 /** 198 * Depth. 199 * 200 * This value is valid with formats HAL_PIXEL_FORMAT_Y16 and HAL_PIXEL_FORMAT_BLOB. 201 */ 202 const val DATASPACE_DEPTH = 4096 203 204 /** 205 * ISO 16684-1:2011(E) Dynamic Depth. 206 * 207 * Embedded depth metadata following the dynamic depth specification. 208 */ 209 const val DATASPACE_DYNAMIC_DEPTH = 4098 210 211 /** 212 * High Efficiency Image File Format (HEIF). 213 * 214 * This value is valid with [HardwareBuffer.BLOB][android.hardware.HardwareBuffer.BLOB] 215 * format. The combination is an HEIC image encoded by HEIC or HEVC encoder according to 216 * ISO/IEC 23008-12. 217 */ 218 const val DATASPACE_HEIF = 4100 219 220 /** 221 * Hybrid Log Gamma encoding. 222 * 223 * Composed of the following - 224 * <pre> 225 * Primaries: STANDARD_BT2020 226 * Transfer: TRANSFER_HLG 227 * Range: RANGE_FULL</pre> 228 */ 229 const val DATASPACE_BT2020_HLG = 168165376 230 231 /** 232 * JPEG File Interchange Format (JFIF). 233 * 234 * Composed of the following - 235 * <pre> 236 * Primaries: STANDARD_BT601_625 237 * Transfer: TRANSFER_SMPTE_170M 238 * Range: RANGE_FULL</pre> 239 * 240 * Same model as BT.601-625, but all values (Y, Cb, Cr) range from `0` to `255` 241 */ 242 const val DATASPACE_JFIF = 146931712 243 244 /** 245 * ISO/IEC TBD 246 * 247 * JPEG image with embedded recovery map following the Jpeg/R specification. 248 * 249 * This value must always remain aligned with the public ImageFormat Jpeg/R definition and 250 * is valid with formats: HAL_PIXEL_FORMAT_BLOB: JPEG image encoded by Jpeg/R encoder 251 * according to ISO/IEC TBD. The image contains a standard SDR JPEG and a recovery map. 252 * Jpeg/R decoders can use the map to recover the input image. 253 */ 254 const val DATASPACE_JPEG_R = 4101 255 256 /** 257 * ITU-R Recommendation 601 (BT.601) - 525-line 258 * 259 * Standard-definition television, 525 Lines (NTSC). 260 * 261 * Composed of the following - 262 * <pre> 263 * Primaries: STANDARD_BT601_625 264 * Transfer: TRANSFER_SMPTE_170M 265 * Range: RANGE_LIMITED</pre> 266 */ 267 const val DATASPACE_BT601_625 = 281149440 268 269 /** 270 * ITU-R Recommendation 709 (BT.709) 271 * 272 * High-definition television. 273 * 274 * Composed of the following - 275 * <pre> 276 * Primaries: STANDARD_BT601_525 277 * Transfer: TRANSFER_SMPTE_170M 278 * Range: RANGE_LIMITED</pre> 279 */ 280 const val DATASPACE_BT601_525 = 281280512 281 282 /** Range characteristics are unknown or are determined by the application. */ 283 const val RANGE_UNSPECIFIED = 0 shl 27 284 285 /** 286 * Full range uses all values for Y, Cb and Cr from `0` to `2^b-1`, where b is the bit depth 287 * of the color format. 288 */ 289 const val RANGE_FULL = 1 shl 27 290 291 /** 292 * Limited range uses values `16/256*2^b` to `235/256*2^b` for Y, and `1/16*2^b` to 293 * `15/16*2^b` for Cb, Cr, R, G and B, where b is the bit depth of the color format. 294 * 295 * E.g. For 8-bit-depth formats: Luma (Y) samples should range from 16 to 235, inclusive 296 * Chroma (Cb, Cr) samples should range from 16 to 240, inclusive 297 * 298 * For 10-bit-depth formats: Luma (Y) samples should range from 64 to 940, inclusive Chroma 299 * (Cb, Cr) samples should range from 64 to 960, inclusive. 300 */ 301 const val RANGE_LIMITED = 2 shl 27 302 303 /** 304 * Extended range can be used in combination with FP16 to communicate scRGB or with 305 * [SurfaceControlCompat.Transaction.setExtendedRangeBrightness] to indicate an HDR range. 306 * 307 * When used with floating point pixel formats and #STANDARD_BT709 then [0.0 - 1.0] is the 308 * standard sRGB space and values outside the range [0.0 - 1.0] can encode color outside the 309 * sRGB gamut. [-0.5, 7.5] is the standard scRGB range. Used to blend/merge multiple 310 * dataspaces on a single display. 311 * 312 * As of [android.os.Build.VERSION_CODES.UPSIDE_DOWN_CAKE] this may be combined with 313 * [SurfaceControlCompat.Transaction.setExtendedRangeBrightness] and other formats such as 314 * [HardwareBuffer.RGBA_8888] or [HardwareBuffer.RGBA_1010102] to communicate a variable HDR 315 * brightness range 316 */ 317 const val RANGE_EXTENDED = 3 shl 27 318 } 319 } 320