1 /* 2 * Copyright (C) 2011 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 #ifndef SYSTEM_CORE_INCLUDE_ANDROID_GRAPHICS_H 18 #define SYSTEM_CORE_INCLUDE_ANDROID_GRAPHICS_H 19 20 #include <stddef.h> 21 #include <stdint.h> 22 23 #ifdef __cplusplus 24 extern "C" { 25 #endif 26 27 /* 28 * If the HAL needs to create service threads to handle graphics related 29 * tasks, these threads need to run at HAL_PRIORITY_URGENT_DISPLAY priority 30 * if they can block the main rendering thread in any way. 31 * 32 * the priority of the current thread can be set with: 33 * 34 * #include <sys/resource.h> 35 * setpriority(PRIO_PROCESS, 0, HAL_PRIORITY_URGENT_DISPLAY); 36 * 37 */ 38 39 #define HAL_PRIORITY_URGENT_DISPLAY (-8) 40 41 /** 42 * pixel format definitions 43 */ 44 45 typedef enum android_pixel_format { 46 /* 47 * "linear" color pixel formats: 48 * 49 * When used with ANativeWindow, the dataSpace field describes the color 50 * space of the buffer. 51 * 52 * The color space determines, for example, if the formats are linear or 53 * gamma-corrected; or whether any special operations are performed when 54 * reading or writing into a buffer in one of these formats. 55 */ 56 HAL_PIXEL_FORMAT_RGBA_8888 = 1, 57 HAL_PIXEL_FORMAT_RGBX_8888 = 2, 58 HAL_PIXEL_FORMAT_RGB_888 = 3, 59 HAL_PIXEL_FORMAT_RGB_565 = 4, 60 HAL_PIXEL_FORMAT_BGRA_8888 = 5, 61 62 /* 63 * 0x100 - 0x1FF 64 * 65 * This range is reserved for pixel formats that are specific to the HAL 66 * implementation. Implementations can use any value in this range to 67 * communicate video pixel formats between their HAL modules. These formats 68 * must not have an alpha channel. Additionally, an EGLimage created from a 69 * gralloc buffer of one of these formats must be supported for use with the 70 * GL_OES_EGL_image_external OpenGL ES extension. 71 */ 72 73 /* 74 * Android YUV format: 75 * 76 * This format is exposed outside of the HAL to software decoders and 77 * applications. EGLImageKHR must support it in conjunction with the 78 * OES_EGL_image_external extension. 79 * 80 * YV12 is a 4:2:0 YCrCb planar format comprised of a WxH Y plane followed 81 * by (W/2) x (H/2) Cr and Cb planes. 82 * 83 * This format assumes 84 * - an even width 85 * - an even height 86 * - a horizontal stride multiple of 16 pixels 87 * - a vertical stride equal to the height 88 * 89 * y_size = stride * height 90 * c_stride = ALIGN(stride/2, 16) 91 * c_size = c_stride * height/2 92 * size = y_size + c_size * 2 93 * cr_offset = y_size 94 * cb_offset = y_size + c_size 95 * 96 * When used with ANativeWindow, the dataSpace field describes the color 97 * space of the buffer. 98 */ 99 HAL_PIXEL_FORMAT_YV12 = 0x32315659, // YCrCb 4:2:0 Planar 100 101 102 /* 103 * Android Y8 format: 104 * 105 * This format is exposed outside of the HAL to the framework. 106 * The expected gralloc usage flags are SW_* and HW_CAMERA_*, 107 * and no other HW_ flags will be used. 108 * 109 * Y8 is a YUV planar format comprised of a WxH Y plane, 110 * with each pixel being represented by 8 bits. 111 * 112 * It is equivalent to just the Y plane from YV12. 113 * 114 * This format assumes 115 * - an even width 116 * - an even height 117 * - a horizontal stride multiple of 16 pixels 118 * - a vertical stride equal to the height 119 * 120 * size = stride * height 121 * 122 * When used with ANativeWindow, the dataSpace field describes the color 123 * space of the buffer. 124 */ 125 HAL_PIXEL_FORMAT_Y8 = 0x20203859, 126 127 /* 128 * Android Y16 format: 129 * 130 * This format is exposed outside of the HAL to the framework. 131 * The expected gralloc usage flags are SW_* and HW_CAMERA_*, 132 * and no other HW_ flags will be used. 133 * 134 * Y16 is a YUV planar format comprised of a WxH Y plane, 135 * with each pixel being represented by 16 bits. 136 * 137 * It is just like Y8, but has double the bits per pixel (little endian). 138 * 139 * This format assumes 140 * - an even width 141 * - an even height 142 * - a horizontal stride multiple of 16 pixels 143 * - a vertical stride equal to the height 144 * - strides are specified in pixels, not in bytes 145 * 146 * size = stride * height * 2 147 * 148 * When used with ANativeWindow, the dataSpace field describes the color 149 * space of the buffer, except that dataSpace field 150 * HAL_DATASPACE_DEPTH indicates that this buffer contains a depth 151 * image where each sample is a distance value measured by a depth camera, 152 * plus an associated confidence value. 153 */ 154 HAL_PIXEL_FORMAT_Y16 = 0x20363159, 155 156 /* 157 * Android RAW sensor format: 158 * 159 * This format is exposed outside of the camera HAL to applications. 160 * 161 * RAW16 is a single-channel, 16-bit, little endian format, typically 162 * representing raw Bayer-pattern images from an image sensor, with minimal 163 * processing. 164 * 165 * The exact pixel layout of the data in the buffer is sensor-dependent, and 166 * needs to be queried from the camera device. 167 * 168 * Generally, not all 16 bits are used; more common values are 10 or 12 169 * bits. If not all bits are used, the lower-order bits are filled first. 170 * All parameters to interpret the raw data (black and white points, 171 * color space, etc) must be queried from the camera device. 172 * 173 * This format assumes 174 * - an even width 175 * - an even height 176 * - a horizontal stride multiple of 16 pixels 177 * - a vertical stride equal to the height 178 * - strides are specified in pixels, not in bytes 179 * 180 * size = stride * height * 2 181 * 182 * This format must be accepted by the gralloc module when used with the 183 * following usage flags: 184 * - GRALLOC_USAGE_HW_CAMERA_* 185 * - GRALLOC_USAGE_SW_* 186 * - GRALLOC_USAGE_RENDERSCRIPT 187 * 188 * When used with ANativeWindow, the dataSpace should be 189 * HAL_DATASPACE_ARBITRARY, as raw image sensor buffers require substantial 190 * extra metadata to define. 191 */ 192 HAL_PIXEL_FORMAT_RAW16 = 0x20, 193 194 /* 195 * Android RAW10 format: 196 * 197 * This format is exposed outside of the camera HAL to applications. 198 * 199 * RAW10 is a single-channel, 10-bit per pixel, densely packed in each row, 200 * unprocessed format, usually representing raw Bayer-pattern images coming from 201 * an image sensor. 202 * 203 * In an image buffer with this format, starting from the first pixel of each 204 * row, each 4 consecutive pixels are packed into 5 bytes (40 bits). Each one 205 * of the first 4 bytes contains the top 8 bits of each pixel, The fifth byte 206 * contains the 2 least significant bits of the 4 pixels, the exact layout data 207 * for each 4 consecutive pixels is illustrated below (Pi[j] stands for the jth 208 * bit of the ith pixel): 209 * 210 * bit 7 bit 0 211 * =====|=====|=====|=====|=====|=====|=====|=====| 212 * Byte 0: |P0[9]|P0[8]|P0[7]|P0[6]|P0[5]|P0[4]|P0[3]|P0[2]| 213 * |-----|-----|-----|-----|-----|-----|-----|-----| 214 * Byte 1: |P1[9]|P1[8]|P1[7]|P1[6]|P1[5]|P1[4]|P1[3]|P1[2]| 215 * |-----|-----|-----|-----|-----|-----|-----|-----| 216 * Byte 2: |P2[9]|P2[8]|P2[7]|P2[6]|P2[5]|P2[4]|P2[3]|P2[2]| 217 * |-----|-----|-----|-----|-----|-----|-----|-----| 218 * Byte 3: |P3[9]|P3[8]|P3[7]|P3[6]|P3[5]|P3[4]|P3[3]|P3[2]| 219 * |-----|-----|-----|-----|-----|-----|-----|-----| 220 * Byte 4: |P3[1]|P3[0]|P2[1]|P2[0]|P1[1]|P1[0]|P0[1]|P0[0]| 221 * =============================================== 222 * 223 * This format assumes 224 * - a width multiple of 4 pixels 225 * - an even height 226 * - a vertical stride equal to the height 227 * - strides are specified in bytes, not in pixels 228 * 229 * size = stride * height 230 * 231 * When stride is equal to width * (10 / 8), there will be no padding bytes at 232 * the end of each row, the entire image data is densely packed. When stride is 233 * larger than width * (10 / 8), padding bytes will be present at the end of each 234 * row (including the last row). 235 * 236 * This format must be accepted by the gralloc module when used with the 237 * following usage flags: 238 * - GRALLOC_USAGE_HW_CAMERA_* 239 * - GRALLOC_USAGE_SW_* 240 * - GRALLOC_USAGE_RENDERSCRIPT 241 * 242 * When used with ANativeWindow, the dataSpace field should be 243 * HAL_DATASPACE_ARBITRARY, as raw image sensor buffers require substantial 244 * extra metadata to define. 245 */ 246 HAL_PIXEL_FORMAT_RAW10 = 0x25, 247 248 /* 249 * Android RAW12 format: 250 * 251 * This format is exposed outside of camera HAL to applications. 252 * 253 * RAW12 is a single-channel, 12-bit per pixel, densely packed in each row, 254 * unprocessed format, usually representing raw Bayer-pattern images coming from 255 * an image sensor. 256 * 257 * In an image buffer with this format, starting from the first pixel of each 258 * row, each two consecutive pixels are packed into 3 bytes (24 bits). The first 259 * and second byte contains the top 8 bits of first and second pixel. The third 260 * byte contains the 4 least significant bits of the two pixels, the exact layout 261 * data for each two consecutive pixels is illustrated below (Pi[j] stands for 262 * the jth bit of the ith pixel): 263 * 264 * bit 7 bit 0 265 * ======|======|======|======|======|======|======|======| 266 * Byte 0: |P0[11]|P0[10]|P0[ 9]|P0[ 8]|P0[ 7]|P0[ 6]|P0[ 5]|P0[ 4]| 267 * |------|------|------|------|------|------|------|------| 268 * Byte 1: |P1[11]|P1[10]|P1[ 9]|P1[ 8]|P1[ 7]|P1[ 6]|P1[ 5]|P1[ 4]| 269 * |------|------|------|------|------|------|------|------| 270 * Byte 2: |P1[ 3]|P1[ 2]|P1[ 1]|P1[ 0]|P0[ 3]|P0[ 2]|P0[ 1]|P0[ 0]| 271 * ======================================================= 272 * 273 * This format assumes: 274 * - a width multiple of 4 pixels 275 * - an even height 276 * - a vertical stride equal to the height 277 * - strides are specified in bytes, not in pixels 278 * 279 * size = stride * height 280 * 281 * When stride is equal to width * (12 / 8), there will be no padding bytes at 282 * the end of each row, the entire image data is densely packed. When stride is 283 * larger than width * (12 / 8), padding bytes will be present at the end of 284 * each row (including the last row). 285 * 286 * This format must be accepted by the gralloc module when used with the 287 * following usage flags: 288 * - GRALLOC_USAGE_HW_CAMERA_* 289 * - GRALLOC_USAGE_SW_* 290 * - GRALLOC_USAGE_RENDERSCRIPT 291 * 292 * When used with ANativeWindow, the dataSpace field should be 293 * HAL_DATASPACE_ARBITRARY, as raw image sensor buffers require substantial 294 * extra metadata to define. 295 */ 296 HAL_PIXEL_FORMAT_RAW12 = 0x26, 297 298 /* 299 * Android opaque RAW format: 300 * 301 * This format is exposed outside of the camera HAL to applications. 302 * 303 * RAW_OPAQUE is a format for unprocessed raw image buffers coming from an 304 * image sensor. The actual structure of buffers of this format is 305 * implementation-dependent. 306 * 307 * This format must be accepted by the gralloc module when used with the 308 * following usage flags: 309 * - GRALLOC_USAGE_HW_CAMERA_* 310 * - GRALLOC_USAGE_SW_* 311 * - GRALLOC_USAGE_RENDERSCRIPT 312 * 313 * When used with ANativeWindow, the dataSpace field should be 314 * HAL_DATASPACE_ARBITRARY, as raw image sensor buffers require substantial 315 * extra metadata to define. 316 */ 317 HAL_PIXEL_FORMAT_RAW_OPAQUE = 0x24, 318 319 /* 320 * Android binary blob graphics buffer format: 321 * 322 * This format is used to carry task-specific data which does not have a 323 * standard image structure. The details of the format are left to the two 324 * endpoints. 325 * 326 * A typical use case is for transporting JPEG-compressed images from the 327 * Camera HAL to the framework or to applications. 328 * 329 * Buffers of this format must have a height of 1, and width equal to their 330 * size in bytes. 331 * 332 * When used with ANativeWindow, the mapping of the dataSpace field to 333 * buffer contents for BLOB is as follows: 334 * 335 * dataSpace value | Buffer contents 336 * -------------------------------+----------------------------------------- 337 * HAL_DATASPACE_JFIF | An encoded JPEG image 338 * HAL_DATASPACE_DEPTH | An android_depth_points buffer 339 * Other | Unsupported 340 * 341 */ 342 HAL_PIXEL_FORMAT_BLOB = 0x21, 343 344 /* 345 * Android format indicating that the choice of format is entirely up to the 346 * device-specific Gralloc implementation. 347 * 348 * The Gralloc implementation should examine the usage bits passed in when 349 * allocating a buffer with this format, and it should derive the pixel 350 * format from those usage flags. This format will never be used with any 351 * of the GRALLOC_USAGE_SW_* usage flags. 352 * 353 * If a buffer of this format is to be used as an OpenGL ES texture, the 354 * framework will assume that sampling the texture will always return an 355 * alpha value of 1.0 (i.e. the buffer contains only opaque pixel values). 356 * 357 * When used with ANativeWindow, the dataSpace field describes the color 358 * space of the buffer. 359 */ 360 HAL_PIXEL_FORMAT_IMPLEMENTATION_DEFINED = 0x22, 361 362 /* 363 * Android flexible YCbCr 4:2:0 formats 364 * 365 * This format allows platforms to use an efficient YCbCr/YCrCb 4:2:0 366 * buffer layout, while still describing the general format in a 367 * layout-independent manner. While called YCbCr, it can be 368 * used to describe formats with either chromatic ordering, as well as 369 * whole planar or semiplanar layouts. 370 * 371 * struct android_ycbcr (below) is the the struct used to describe it. 372 * 373 * This format must be accepted by the gralloc module when 374 * USAGE_SW_WRITE_* or USAGE_SW_READ_* are set. 375 * 376 * This format is locked for use by gralloc's (*lock_ycbcr) method, and 377 * locking with the (*lock) method will return an error. 378 * 379 * When used with ANativeWindow, the dataSpace field describes the color 380 * space of the buffer. 381 */ 382 HAL_PIXEL_FORMAT_YCbCr_420_888 = 0x23, 383 384 /* 385 * Android flexible YCbCr 4:2:2 formats 386 * 387 * This format allows platforms to use an efficient YCbCr/YCrCb 4:2:2 388 * buffer layout, while still describing the general format in a 389 * layout-independent manner. While called YCbCr, it can be 390 * used to describe formats with either chromatic ordering, as well as 391 * whole planar or semiplanar layouts. 392 * 393 * This format is currently only used by SW readable buffers 394 * produced by MediaCodecs, so the gralloc module can ignore this format. 395 */ 396 HAL_PIXEL_FORMAT_YCbCr_422_888 = 0x27, 397 398 /* 399 * Android flexible YCbCr 4:4:4 formats 400 * 401 * This format allows platforms to use an efficient YCbCr/YCrCb 4:4:4 402 * buffer layout, while still describing the general format in a 403 * layout-independent manner. While called YCbCr, it can be 404 * used to describe formats with either chromatic ordering, as well as 405 * whole planar or semiplanar layouts. 406 * 407 * This format is currently only used by SW readable buffers 408 * produced by MediaCodecs, so the gralloc module can ignore this format. 409 */ 410 HAL_PIXEL_FORMAT_YCbCr_444_888 = 0x28, 411 412 /* 413 * Android flexible RGB 888 formats 414 * 415 * This format allows platforms to use an efficient RGB/BGR/RGBX/BGRX 416 * buffer layout, while still describing the general format in a 417 * layout-independent manner. While called RGB, it can be 418 * used to describe formats with either color ordering and optional 419 * padding, as well as whole planar layout. 420 * 421 * This format is currently only used by SW readable buffers 422 * produced by MediaCodecs, so the gralloc module can ignore this format. 423 */ 424 HAL_PIXEL_FORMAT_FLEX_RGB_888 = 0x29, 425 426 /* 427 * Android flexible RGBA 8888 formats 428 * 429 * This format allows platforms to use an efficient RGBA/BGRA/ARGB/ABGR 430 * buffer layout, while still describing the general format in a 431 * layout-independent manner. While called RGBA, it can be 432 * used to describe formats with any of the component orderings, as 433 * well as whole planar layout. 434 * 435 * This format is currently only used by SW readable buffers 436 * produced by MediaCodecs, so the gralloc module can ignore this format. 437 */ 438 HAL_PIXEL_FORMAT_FLEX_RGBA_8888 = 0x2A, 439 440 /* Legacy formats (deprecated), used by ImageFormat.java */ 441 HAL_PIXEL_FORMAT_YCbCr_422_SP = 0x10, // NV16 442 HAL_PIXEL_FORMAT_YCrCb_420_SP = 0x11, // NV21 443 HAL_PIXEL_FORMAT_YCbCr_422_I = 0x14, // YUY2 444 } android_pixel_format_t; 445 446 /* 447 * Structure for describing YCbCr formats for consumption by applications. 448 * This is used with HAL_PIXEL_FORMAT_YCbCr_*_888. 449 * 450 * Buffer chroma subsampling is defined in the format. 451 * e.g. HAL_PIXEL_FORMAT_YCbCr_420_888 has subsampling 4:2:0. 452 * 453 * Buffers must have a 8 bit depth. 454 * 455 * @y, @cb, and @cr point to the first byte of their respective planes. 456 * 457 * Stride describes the distance in bytes from the first value of one row of 458 * the image to the first value of the next row. It includes the width of the 459 * image plus padding. 460 * @ystride is the stride of the luma plane. 461 * @cstride is the stride of the chroma planes. 462 * 463 * @chroma_step is the distance in bytes from one chroma pixel value to the 464 * next. This is 2 bytes for semiplanar (because chroma values are interleaved 465 * and each chroma value is one byte) and 1 for planar. 466 */ 467 468 struct android_ycbcr { 469 void *y; 470 void *cb; 471 void *cr; 472 size_t ystride; 473 size_t cstride; 474 size_t chroma_step; 475 476 /** reserved for future use, set to 0 by gralloc's (*lock_ycbcr)() */ 477 uint32_t reserved[8]; 478 }; 479 480 /** 481 * Structure used to define depth point clouds for format HAL_PIXEL_FORMAT_BLOB 482 * with dataSpace value of HAL_DATASPACE_DEPTH. 483 * When locking a native buffer of the above format and dataSpace value, 484 * the vaddr pointer can be cast to this structure. 485 * 486 * A variable-length list of (x,y,z, confidence) 3D points, as floats. (x, y, 487 * z) represents a measured point's position, with the coordinate system defined 488 * by the data source. Confidence represents the estimated likelihood that this 489 * measurement is correct. It is between 0.f and 1.f, inclusive, with 1.f == 490 * 100% confidence. 491 * 492 * @num_points is the number of points in the list 493 * 494 * @xyz_points is the flexible array of floating-point values. 495 * It contains (num_points) * 4 floats. 496 * 497 * For example: 498 * android_depth_points d = get_depth_buffer(); 499 * struct { 500 * float x; float y; float z; float confidence; 501 * } firstPoint, lastPoint; 502 * 503 * firstPoint.x = d.xyzc_points[0]; 504 * firstPoint.y = d.xyzc_points[1]; 505 * firstPoint.z = d.xyzc_points[2]; 506 * firstPoint.confidence = d.xyzc_points[3]; 507 * lastPoint.x = d.xyzc_points[(d.num_points - 1) * 4 + 0]; 508 * lastPoint.y = d.xyzc_points[(d.num_points - 1) * 4 + 1]; 509 * lastPoint.z = d.xyzc_points[(d.num_points - 1) * 4 + 2]; 510 * lastPoint.confidence = d.xyzc_points[(d.num_points - 1) * 4 + 3]; 511 */ 512 513 struct android_depth_points { 514 uint32_t num_points; 515 516 /** reserved for future use, set to 0 by gralloc's (*lock)() */ 517 uint32_t reserved[8]; 518 519 float xyzc_points[]; 520 }; 521 522 /** 523 * Transformation definitions 524 * 525 * IMPORTANT NOTE: 526 * HAL_TRANSFORM_ROT_90 is applied CLOCKWISE and AFTER HAL_TRANSFORM_FLIP_{H|V}. 527 * 528 */ 529 530 typedef enum android_transform { 531 /* flip source image horizontally (around the vertical axis) */ 532 HAL_TRANSFORM_FLIP_H = 0x01, 533 /* flip source image vertically (around the horizontal axis)*/ 534 HAL_TRANSFORM_FLIP_V = 0x02, 535 /* rotate source image 90 degrees clockwise */ 536 HAL_TRANSFORM_ROT_90 = 0x04, 537 /* rotate source image 180 degrees */ 538 HAL_TRANSFORM_ROT_180 = 0x03, 539 /* rotate source image 270 degrees clockwise */ 540 HAL_TRANSFORM_ROT_270 = 0x07, 541 /* don't use. see system/window.h */ 542 HAL_TRANSFORM_RESERVED = 0x08, 543 } android_transform_t; 544 545 /** 546 * Dataspace Definitions 547 * ====================== 548 * 549 * Dataspace is the definition of how pixel values should be interpreted. 550 * 551 * For many formats, this is the colorspace of the image data, which includes 552 * primaries (including white point) and the transfer characteristic function, 553 * which describes both gamma curve and numeric range (within the bit depth). 554 * 555 * Other dataspaces include depth measurement data from a depth camera. 556 * 557 * A dataspace is comprised of a number of fields. 558 * 559 * Version 560 * -------- 561 * The top 2 bits represent the revision of the field specification. This is 562 * currently always 0. 563 * 564 * 565 * bits 31-30 29 - 0 566 * +-----+----------------------------------------------------+ 567 * fields | Rev | Revision specific fields | 568 * +-----+----------------------------------------------------+ 569 * 570 * Field layout for version = 0: 571 * ---------------------------- 572 * 573 * A dataspace is comprised of the following fields: 574 * Standard 575 * Transfer function 576 * Range 577 * 578 * bits 31-30 29-27 26 - 22 21 - 16 15 - 0 579 * +-----+-----+--------+--------+----------------------------+ 580 * fields | 0 |Range|Transfer|Standard| Legacy and custom | 581 * +-----+-----+--------+--------+----------------------------+ 582 * VV RRR TTTTT SSSSSS LLLLLLLL LLLLLLLL 583 * 584 * If range, transfer and standard fields are all 0 (e.g. top 16 bits are 585 * all zeroes), the bottom 16 bits contain either a legacy dataspace value, 586 * or a custom value. 587 */ 588 589 typedef enum android_dataspace { 590 /* 591 * Default-assumption data space, when not explicitly specified. 592 * 593 * It is safest to assume the buffer is an image with sRGB primaries and 594 * encoding ranges, but the consumer and/or the producer of the data may 595 * simply be using defaults. No automatic gamma transform should be 596 * expected, except for a possible display gamma transform when drawn to a 597 * screen. 598 */ 599 HAL_DATASPACE_UNKNOWN = 0x0, 600 601 /* 602 * Arbitrary dataspace with manually defined characteristics. Definition 603 * for colorspaces or other meaning must be communicated separately. 604 * 605 * This is used when specifying primaries, transfer characteristics, 606 * etc. separately. 607 * 608 * A typical use case is in video encoding parameters (e.g. for H.264), 609 * where a colorspace can have separately defined primaries, transfer 610 * characteristics, etc. 611 */ 612 HAL_DATASPACE_ARBITRARY = 0x1, 613 614 /* 615 * Color-description aspects 616 * 617 * The following aspects define various characteristics of the color 618 * specification. These represent bitfields, so that a data space value 619 * can specify each of them independently. 620 */ 621 622 HAL_DATASPACE_STANDARD_SHIFT = 16, 623 624 /* 625 * Standard aspect 626 * 627 * Defines the chromaticity coordinates of the source primaries in terms of 628 * the CIE 1931 definition of x and y specified in ISO 11664-1. 629 */ 630 HAL_DATASPACE_STANDARD_MASK = 63 << HAL_DATASPACE_STANDARD_SHIFT, // 0x3F 631 632 /* 633 * Chromacity coordinates are unknown or are determined by the application. 634 * Implementations shall use the following suggested standards: 635 * 636 * All YCbCr formats: BT709 if size is 720p or larger (since most video 637 * content is letterboxed this corresponds to width is 638 * 1280 or greater, or height is 720 or greater). 639 * BT601_625 if size is smaller than 720p or is JPEG. 640 * All RGB formats: BT709. 641 * 642 * For all other formats standard is undefined, and implementations should use 643 * an appropriate standard for the data represented. 644 */ 645 HAL_DATASPACE_STANDARD_UNSPECIFIED = 0 << HAL_DATASPACE_STANDARD_SHIFT, 646 647 /* 648 * Primaries: x y 649 * green 0.300 0.600 650 * blue 0.150 0.060 651 * red 0.640 0.330 652 * white (D65) 0.3127 0.3290 653 * 654 * Use the unadjusted KR = 0.2126, KB = 0.0722 luminance interpretation 655 * for RGB conversion. 656 */ 657 HAL_DATASPACE_STANDARD_BT709 = 1 << HAL_DATASPACE_STANDARD_SHIFT, 658 659 /* 660 * Primaries: x y 661 * green 0.290 0.600 662 * blue 0.150 0.060 663 * red 0.640 0.330 664 * white (D65) 0.3127 0.3290 665 * 666 * KR = 0.299, KB = 0.114. This adjusts the luminance interpretation 667 * for RGB conversion from the one purely determined by the primaries 668 * to minimize the color shift into RGB space that uses BT.709 669 * primaries. 670 */ 671 HAL_DATASPACE_STANDARD_BT601_625 = 2 << HAL_DATASPACE_STANDARD_SHIFT, 672 673 /* 674 * Primaries: x y 675 * green 0.290 0.600 676 * blue 0.150 0.060 677 * red 0.640 0.330 678 * white (D65) 0.3127 0.3290 679 * 680 * Use the unadjusted KR = 0.222, KB = 0.071 luminance interpretation 681 * for RGB conversion. 682 */ 683 HAL_DATASPACE_STANDARD_BT601_625_UNADJUSTED = 3 << HAL_DATASPACE_STANDARD_SHIFT, 684 685 /* 686 * Primaries: x y 687 * green 0.310 0.595 688 * blue 0.155 0.070 689 * red 0.630 0.340 690 * white (D65) 0.3127 0.3290 691 * 692 * KR = 0.299, KB = 0.114. This adjusts the luminance interpretation 693 * for RGB conversion from the one purely determined by the primaries 694 * to minimize the color shift into RGB space that uses BT.709 695 * primaries. 696 */ 697 HAL_DATASPACE_STANDARD_BT601_525 = 4 << HAL_DATASPACE_STANDARD_SHIFT, 698 699 /* 700 * Primaries: x y 701 * green 0.310 0.595 702 * blue 0.155 0.070 703 * red 0.630 0.340 704 * white (D65) 0.3127 0.3290 705 * 706 * Use the unadjusted KR = 0.212, KB = 0.087 luminance interpretation 707 * for RGB conversion (as in SMPTE 240M). 708 */ 709 HAL_DATASPACE_STANDARD_BT601_525_UNADJUSTED = 5 << HAL_DATASPACE_STANDARD_SHIFT, 710 711 /* 712 * Primaries: x y 713 * green 0.170 0.797 714 * blue 0.131 0.046 715 * red 0.708 0.292 716 * white (D65) 0.3127 0.3290 717 * 718 * Use the unadjusted KR = 0.2627, KB = 0.0593 luminance interpretation 719 * for RGB conversion. 720 */ 721 HAL_DATASPACE_STANDARD_BT2020 = 6 << HAL_DATASPACE_STANDARD_SHIFT, 722 723 /* 724 * Primaries: x y 725 * green 0.170 0.797 726 * blue 0.131 0.046 727 * red 0.708 0.292 728 * white (D65) 0.3127 0.3290 729 * 730 * Use the unadjusted KR = 0.2627, KB = 0.0593 luminance interpretation 731 * for RGB conversion using the linear domain. 732 */ 733 HAL_DATASPACE_STANDARD_BT2020_CONSTANT_LUMINANCE = 7 << HAL_DATASPACE_STANDARD_SHIFT, 734 735 /* 736 * Primaries: x y 737 * green 0.21 0.71 738 * blue 0.14 0.08 739 * red 0.67 0.33 740 * white (C) 0.310 0.316 741 * 742 * Use the unadjusted KR = 0.30, KB = 0.11 luminance interpretation 743 * for RGB conversion. 744 */ 745 HAL_DATASPACE_STANDARD_BT470M = 8 << HAL_DATASPACE_STANDARD_SHIFT, 746 747 /* 748 * Primaries: x y 749 * green 0.243 0.692 750 * blue 0.145 0.049 751 * red 0.681 0.319 752 * white (C) 0.310 0.316 753 * 754 * Use the unadjusted KR = 0.254, KB = 0.068 luminance interpretation 755 * for RGB conversion. 756 */ 757 HAL_DATASPACE_STANDARD_FILM = 9 << HAL_DATASPACE_STANDARD_SHIFT, 758 759 HAL_DATASPACE_TRANSFER_SHIFT = 22, 760 761 /* 762 * Transfer aspect 763 * 764 * Transfer characteristics are the opto-electronic transfer characteristic 765 * at the source as a function of linear optical intensity (luminance). 766 * 767 * For digital signals, E corresponds to the recorded value. Normally, the 768 * transfer function is applied in RGB space to each of the R, G and B 769 * components independently. This may result in color shift that can be 770 * minized by applying the transfer function in Lab space only for the L 771 * component. Implementation may apply the transfer function in RGB space 772 * for all pixel formats if desired. 773 */ 774 775 HAL_DATASPACE_TRANSFER_MASK = 31 << HAL_DATASPACE_TRANSFER_SHIFT, // 0x1F 776 777 /* 778 * Transfer characteristics are unknown or are determined by the 779 * application. 780 * 781 * Implementations should use the following transfer functions: 782 * 783 * For YCbCr formats: use HAL_DATASPACE_TRANSFER_SMPTE_170M 784 * For RGB formats: use HAL_DATASPACE_TRANSFER_SRGB 785 * 786 * For all other formats transfer function is undefined, and implementations 787 * should use an appropriate standard for the data represented. 788 */ 789 HAL_DATASPACE_TRANSFER_UNSPECIFIED = 0 << HAL_DATASPACE_TRANSFER_SHIFT, 790 791 /* 792 * Transfer characteristic curve: 793 * E = L 794 * L - luminance of image 0 <= L <= 1 for conventional colorimetry 795 * E - corresponding electrical signal 796 */ 797 HAL_DATASPACE_TRANSFER_LINEAR = 1 << HAL_DATASPACE_TRANSFER_SHIFT, 798 799 /* 800 * Transfer characteristic curve: 801 * 802 * E = 1.055 * L^(1/2.4) - 0.055 for 0.0031308 <= L <= 1 803 * = 12.92 * L for 0 <= L < 0.0031308 804 * L - luminance of image 0 <= L <= 1 for conventional colorimetry 805 * E - corresponding electrical signal 806 */ 807 HAL_DATASPACE_TRANSFER_SRGB = 2 << HAL_DATASPACE_TRANSFER_SHIFT, 808 809 /* 810 * BT.601 525, BT.601 625, BT.709, BT.2020 811 * 812 * Transfer characteristic curve: 813 * E = 1.099 * L ^ 0.45 - 0.099 for 0.018 <= L <= 1 814 * = 4.500 * L for 0 <= L < 0.018 815 * L - luminance of image 0 <= L <= 1 for conventional colorimetry 816 * E - corresponding electrical signal 817 */ 818 HAL_DATASPACE_TRANSFER_SMPTE_170M = 3 << HAL_DATASPACE_TRANSFER_SHIFT, 819 820 /* 821 * Assumed display gamma 2.2. 822 * 823 * Transfer characteristic curve: 824 * E = L ^ (1/2.2) 825 * L - luminance of image 0 <= L <= 1 for conventional colorimetry 826 * E - corresponding electrical signal 827 */ 828 HAL_DATASPACE_TRANSFER_GAMMA2_2 = 4 << HAL_DATASPACE_TRANSFER_SHIFT, 829 830 /* 831 * display gamma 2.8. 832 * 833 * Transfer characteristic curve: 834 * E = L ^ (1/2.8) 835 * L - luminance of image 0 <= L <= 1 for conventional colorimetry 836 * E - corresponding electrical signal 837 */ 838 HAL_DATASPACE_TRANSFER_GAMMA2_8 = 5 << HAL_DATASPACE_TRANSFER_SHIFT, 839 840 /* 841 * SMPTE ST 2084 842 * 843 * Transfer characteristic curve: 844 * E = ((c1 + c2 * L^n) / (1 + c3 * L^n)) ^ m 845 * c1 = c3 - c2 + 1 = 3424 / 4096 = 0.8359375 846 * c2 = 32 * 2413 / 4096 = 18.8515625 847 * c3 = 32 * 2392 / 4096 = 18.6875 848 * m = 128 * 2523 / 4096 = 78.84375 849 * n = 0.25 * 2610 / 4096 = 0.1593017578125 850 * L - luminance of image 0 <= L <= 1 for HDR colorimetry. 851 * L = 1 corresponds to 10000 cd/m2 852 * E - corresponding electrical signal 853 */ 854 HAL_DATASPACE_TRANSFER_ST2084 = 6 << HAL_DATASPACE_TRANSFER_SHIFT, 855 856 /* 857 * ARIB STD-B67 Hybrid Log Gamma 858 * 859 * Transfer characteristic curve: 860 * E = r * L^0.5 for 0 <= L <= 1 861 * = a * ln(L - b) + c for 1 < L 862 * a = 0.17883277 863 * b = 0.28466892 864 * c = 0.55991073 865 * r = 0.5 866 * L - luminance of image 0 <= L for HDR colorimetry. L = 1 corresponds 867 * to reference white level of 100 cd/m2 868 * E - corresponding electrical signal 869 */ 870 HAL_DATASPACE_TRANSFER_HLG = 7 << HAL_DATASPACE_TRANSFER_SHIFT, 871 872 HAL_DATASPACE_RANGE_SHIFT = 27, 873 874 /* 875 * Range aspect 876 * 877 * Defines the range of values corresponding to the unit range of 0-1. 878 * This is defined for YCbCr only, but can be expanded to RGB space. 879 */ 880 HAL_DATASPACE_RANGE_MASK = 7 << HAL_DATASPACE_RANGE_SHIFT, // 0x7 881 882 /* 883 * Range is unknown or are determined by the application. Implementations 884 * shall use the following suggested ranges: 885 * 886 * All YCbCr formats: limited range. 887 * All RGB or RGBA formats (including RAW and Bayer): full range. 888 * All Y formats: full range 889 * 890 * For all other formats range is undefined, and implementations should use 891 * an appropriate range for the data represented. 892 */ 893 HAL_DATASPACE_RANGE_UNSPECIFIED = 0 << HAL_DATASPACE_RANGE_SHIFT, 894 895 /* 896 * Full range uses all values for Y, Cb and Cr from 897 * 0 to 2^b-1, where b is the bit depth of the color format. 898 */ 899 HAL_DATASPACE_RANGE_FULL = 1 << HAL_DATASPACE_RANGE_SHIFT, 900 901 /* 902 * Limited range uses values 16/256*2^b to 235/256*2^b for Y, and 903 * 1/16*2^b to 15/16*2^b for Cb, Cr, R, G and B, where b is the bit depth of 904 * the color format. 905 * 906 * E.g. For 8-bit-depth formats: 907 * Luma (Y) samples should range from 16 to 235, inclusive 908 * Chroma (Cb, Cr) samples should range from 16 to 240, inclusive 909 * 910 * For 10-bit-depth formats: 911 * Luma (Y) samples should range from 64 to 940, inclusive 912 * Chroma (Cb, Cr) samples should range from 64 to 960, inclusive 913 */ 914 HAL_DATASPACE_RANGE_LIMITED = 2 << HAL_DATASPACE_RANGE_SHIFT, 915 916 /* 917 * Legacy dataspaces 918 */ 919 920 /* 921 * sRGB linear encoding: 922 * 923 * The red, green, and blue components are stored in sRGB space, but 924 * are linear, not gamma-encoded. 925 * The RGB primaries and the white point are the same as BT.709. 926 * 927 * The values are encoded using the full range ([0,255] for 8-bit) for all 928 * components. 929 */ 930 HAL_DATASPACE_SRGB_LINEAR = 0x200, // deprecated, use HAL_DATASPACE_V0_SRGB_LINEAR 931 932 HAL_DATASPACE_V0_SRGB_LINEAR = HAL_DATASPACE_STANDARD_BT709 | 933 HAL_DATASPACE_TRANSFER_LINEAR | HAL_DATASPACE_RANGE_FULL, 934 935 936 /* 937 * sRGB gamma encoding: 938 * 939 * The red, green and blue components are stored in sRGB space, and 940 * converted to linear space when read, using the SRGB transfer function 941 * for each of the R, G and B components. When written, the inverse 942 * transformation is performed. 943 * 944 * The alpha component, if present, is always stored in linear space and 945 * is left unmodified when read or written. 946 * 947 * Use full range and BT.709 standard. 948 */ 949 HAL_DATASPACE_SRGB = 0x201, // deprecated, use HAL_DATASPACE_V0_SRGB 950 951 HAL_DATASPACE_V0_SRGB = HAL_DATASPACE_STANDARD_BT709 | 952 HAL_DATASPACE_TRANSFER_SRGB | HAL_DATASPACE_RANGE_FULL, 953 954 955 /* 956 * YCbCr Colorspaces 957 * ----------------- 958 * 959 * Primaries are given using (x,y) coordinates in the CIE 1931 definition 960 * of x and y specified by ISO 11664-1. 961 * 962 * Transfer characteristics are the opto-electronic transfer characteristic 963 * at the source as a function of linear optical intensity (luminance). 964 */ 965 966 /* 967 * JPEG File Interchange Format (JFIF) 968 * 969 * Same model as BT.601-625, but all values (Y, Cb, Cr) range from 0 to 255 970 * 971 * Use full range, BT.601 transfer and BT.601_625 standard. 972 */ 973 HAL_DATASPACE_JFIF = 0x101, // deprecated, use HAL_DATASPACE_V0_JFIF 974 975 HAL_DATASPACE_V0_JFIF = HAL_DATASPACE_STANDARD_BT601_625 | 976 HAL_DATASPACE_TRANSFER_SMPTE_170M | HAL_DATASPACE_RANGE_FULL, 977 978 /* 979 * ITU-R Recommendation 601 (BT.601) - 625-line 980 * 981 * Standard-definition television, 625 Lines (PAL) 982 * 983 * Use limited range, BT.601 transfer and BT.601_625 standard. 984 */ 985 HAL_DATASPACE_BT601_625 = 0x102, // deprecated, use HAL_DATASPACE_V0_BT601_625 986 987 HAL_DATASPACE_V0_BT601_625 = HAL_DATASPACE_STANDARD_BT601_625 | 988 HAL_DATASPACE_TRANSFER_SMPTE_170M | HAL_DATASPACE_RANGE_LIMITED, 989 990 991 /* 992 * ITU-R Recommendation 601 (BT.601) - 525-line 993 * 994 * Standard-definition television, 525 Lines (NTSC) 995 * 996 * Use limited range, BT.601 transfer and BT.601_525 standard. 997 */ 998 HAL_DATASPACE_BT601_525 = 0x103, // deprecated, use HAL_DATASPACE_V0_BT601_525 999 1000 HAL_DATASPACE_V0_BT601_525 = HAL_DATASPACE_STANDARD_BT601_525 | 1001 HAL_DATASPACE_TRANSFER_SMPTE_170M | HAL_DATASPACE_RANGE_LIMITED, 1002 1003 /* 1004 * ITU-R Recommendation 709 (BT.709) 1005 * 1006 * High-definition television 1007 * 1008 * Use limited range, BT.709 transfer and BT.709 standard. 1009 */ 1010 HAL_DATASPACE_BT709 = 0x104, // deprecated, use HAL_DATASPACE_V0_BT709 1011 1012 HAL_DATASPACE_V0_BT709 = HAL_DATASPACE_STANDARD_BT709 | 1013 HAL_DATASPACE_TRANSFER_SMPTE_170M | HAL_DATASPACE_RANGE_LIMITED, 1014 1015 /* 1016 * Data spaces for non-color formats 1017 */ 1018 1019 /* 1020 * The buffer contains depth ranging measurements from a depth camera. 1021 * This value is valid with formats: 1022 * HAL_PIXEL_FORMAT_Y16: 16-bit samples, consisting of a depth measurement 1023 * and an associated confidence value. The 3 MSBs of the sample make 1024 * up the confidence value, and the low 13 LSBs of the sample make up 1025 * the depth measurement. 1026 * For the confidence section, 0 means 100% confidence, 1 means 0% 1027 * confidence. The mapping to a linear float confidence value between 1028 * 0.f and 1.f can be obtained with 1029 * float confidence = (((depthSample >> 13) - 1) & 0x7) / 7.0f; 1030 * The depth measurement can be extracted simply with 1031 * uint16_t range = (depthSample & 0x1FFF); 1032 * HAL_PIXEL_FORMAT_BLOB: A depth point cloud, as 1033 * a variable-length float (x,y,z, confidence) coordinate point list. 1034 * The point cloud will be represented with the android_depth_points 1035 * structure. 1036 */ 1037 HAL_DATASPACE_DEPTH = 0x1000 1038 1039 } android_dataspace_t; 1040 1041 /* 1042 * Color transforms that may be applied by hardware composer to the whole 1043 * display. 1044 */ 1045 typedef enum android_color_transform { 1046 /* Applies no transform to the output color */ 1047 HAL_COLOR_TRANSFORM_IDENTITY = 0, 1048 1049 /* Applies an arbitrary transform defined by a 4x4 affine matrix */ 1050 HAL_COLOR_TRANSFORM_ARBITRARY_MATRIX = 1, 1051 1052 /* Applies a transform that inverts the value or luminance of the color, but 1053 * does not modify hue or saturation */ 1054 HAL_COLOR_TRANSFORM_VALUE_INVERSE = 2, 1055 1056 /* Applies a transform that maps all colors to shades of gray */ 1057 HAL_COLOR_TRANSFORM_GRAYSCALE = 3, 1058 1059 /* Applies a transform which corrects for protanopic color blindness */ 1060 HAL_COLOR_TRANSFORM_CORRECT_PROTANOPIA = 4, 1061 1062 /* Applies a transform which corrects for deuteranopic color blindness */ 1063 HAL_COLOR_TRANSFORM_CORRECT_DEUTERANOPIA = 5, 1064 1065 /* Applies a transform which corrects for tritanopic color blindness */ 1066 HAL_COLOR_TRANSFORM_CORRECT_TRITANOPIA = 6 1067 } android_color_transform_t; 1068 1069 /* 1070 * Supported HDR formats. Must be kept in sync with equivalents in Display.java. 1071 */ 1072 typedef enum android_hdr { 1073 /* Device supports Dolby Vision HDR */ 1074 HAL_HDR_DOLBY_VISION = 1, 1075 1076 /* Device supports HDR10 */ 1077 HAL_HDR_HDR10 = 2, 1078 1079 /* Device supports hybrid log-gamma HDR */ 1080 HAL_HDR_HLG = 3 1081 } android_hdr_t; 1082 1083 #ifdef __cplusplus 1084 } 1085 #endif 1086 1087 #endif /* SYSTEM_CORE_INCLUDE_ANDROID_GRAPHICS_H */ 1088