graphics.h revision 72fce30eeb2a3eecaefc858ffb0a478a41196572
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 <stdint.h> 21 22#ifdef __cplusplus 23extern "C" { 24#endif 25 26/* 27 * If the HAL needs to create service threads to handle graphics related 28 * tasks, these threads need to run at HAL_PRIORITY_URGENT_DISPLAY priority 29 * if they can block the main rendering thread in any way. 30 * 31 * the priority of the current thread can be set with: 32 * 33 * #include <sys/resource.h> 34 * setpriority(PRIO_PROCESS, 0, HAL_PRIORITY_URGENT_DISPLAY); 35 * 36 */ 37 38#define HAL_PRIORITY_URGENT_DISPLAY (-8) 39 40/** 41 * pixel format definitions 42 */ 43 44enum { 45 /* 46 * "linear" color pixel formats: 47 * 48 * The pixel formats below contain sRGB data but are otherwise treated 49 * as linear formats, i.e.: no special operation is performed when 50 * reading or writing into a buffer in one of these formats 51 */ 52 HAL_PIXEL_FORMAT_RGBA_8888 = 1, 53 HAL_PIXEL_FORMAT_RGBX_8888 = 2, 54 HAL_PIXEL_FORMAT_RGB_888 = 3, 55 HAL_PIXEL_FORMAT_RGB_565 = 4, 56 HAL_PIXEL_FORMAT_BGRA_8888 = 5, 57 58 /* 59 * sRGB color pixel formats: 60 * 61 * The red, green and blue components are stored in sRGB space, and converted 62 * to linear space when read, using the standard sRGB to linear equation: 63 * 64 * Clinear = Csrgb / 12.92 for Csrgb <= 0.04045 65 * = (Csrgb + 0.055 / 1.055)^2.4 for Csrgb > 0.04045 66 * 67 * When written the inverse transformation is performed: 68 * 69 * Csrgb = 12.92 * Clinear for Clinear <= 0.0031308 70 * = 1.055 * Clinear^(1/2.4) - 0.055 for Clinear > 0.0031308 71 * 72 * 73 * The alpha component, if present, is always stored in linear space and 74 * is left unmodified when read or written. 75 * 76 */ 77 HAL_PIXEL_FORMAT_sRGB_A_8888 = 0xC, 78 HAL_PIXEL_FORMAT_sRGB_X_8888 = 0xD, 79 80 /* 81 * 0x100 - 0x1FF 82 * 83 * This range is reserved for pixel formats that are specific to the HAL 84 * implementation. Implementations can use any value in this range to 85 * communicate video pixel formats between their HAL modules. These formats 86 * must not have an alpha channel. Additionally, an EGLimage created from a 87 * gralloc buffer of one of these formats must be supported for use with the 88 * GL_OES_EGL_image_external OpenGL ES extension. 89 */ 90 91 /* 92 * Android YUV format: 93 * 94 * This format is exposed outside of the HAL to software decoders and 95 * applications. EGLImageKHR must support it in conjunction with the 96 * OES_EGL_image_external extension. 97 * 98 * YV12 is a 4:2:0 YCrCb planar format comprised of a WxH Y plane followed 99 * by (W/2) x (H/2) Cr and Cb planes. 100 * 101 * This format assumes 102 * - an even width 103 * - an even height 104 * - a horizontal stride multiple of 16 pixels 105 * - a vertical stride equal to the height 106 * 107 * y_size = stride * height 108 * c_stride = ALIGN(stride/2, 16) 109 * c_size = c_stride * height/2 110 * size = y_size + c_size * 2 111 * cr_offset = y_size 112 * cb_offset = y_size + c_size 113 * 114 */ 115 HAL_PIXEL_FORMAT_YV12 = 0x32315659, // YCrCb 4:2:0 Planar 116 117 118 /* 119 * Android Y8 format: 120 * 121 * This format is exposed outside of the HAL to the framework. 122 * The expected gralloc usage flags are SW_* and HW_CAMERA_*, 123 * and no other HW_ flags will be used. 124 * 125 * Y8 is a YUV planar format comprised of a WxH Y plane, 126 * with each pixel being represented by 8 bits. 127 * 128 * It is equivalent to just the Y plane from YV12. 129 * 130 * This format assumes 131 * - an even width 132 * - an even height 133 * - a horizontal stride multiple of 16 pixels 134 * - a vertical stride equal to the height 135 * 136 * size = stride * height 137 * 138 */ 139 HAL_PIXEL_FORMAT_Y8 = 0x20203859, 140 141 /* 142 * Android Y16 format: 143 * 144 * This format is exposed outside of the HAL to the framework. 145 * The expected gralloc usage flags are SW_* and HW_CAMERA_*, 146 * and no other HW_ flags will be used. 147 * 148 * Y16 is a YUV planar format comprised of a WxH Y plane, 149 * with each pixel being represented by 16 bits. 150 * 151 * It is just like Y8, but has double the bits per pixel (little endian). 152 * 153 * This format assumes 154 * - an even width 155 * - an even height 156 * - a horizontal stride multiple of 16 pixels 157 * - a vertical stride equal to the height 158 * - strides are specified in pixels, not in bytes 159 * 160 * size = stride * height * 2 161 * 162 */ 163 HAL_PIXEL_FORMAT_Y16 = 0x20363159, 164 165 /* 166 * Android RAW sensor format: 167 * 168 * This format is exposed outside of the camera HAL to applications. 169 * 170 * RAW_SENSOR is a single-channel, 16-bit, little endian format, typically 171 * representing raw Bayer-pattern images from an image sensor, with minimal 172 * processing. 173 * 174 * The exact pixel layout of the data in the buffer is sensor-dependent, and 175 * needs to be queried from the camera device. 176 * 177 * Generally, not all 16 bits are used; more common values are 10 or 12 178 * bits. If not all bits are used, the lower-order bits are filled first. 179 * All parameters to interpret the raw data (black and white points, 180 * color space, etc) must be queried from the camera device. 181 * 182 * This format assumes 183 * - an even width 184 * - an even height 185 * - a horizontal stride multiple of 16 pixels 186 * - a vertical stride equal to the height 187 * - strides are specified in pixels, not in bytes 188 * 189 * size = stride * height * 2 190 * 191 * This format must be accepted by the gralloc module when used with the 192 * following usage flags: 193 * - GRALLOC_USAGE_HW_CAMERA_* 194 * - GRALLOC_USAGE_SW_* 195 * - GRALLOC_USAGE_RENDERSCRIPT 196 */ 197 HAL_PIXEL_FORMAT_RAW16 = 0x20, 198 HAL_PIXEL_FORMAT_RAW_SENSOR = 0x20, // TODO(rubenbrunk): Remove RAW_SENSOR. 199 200 /* 201 * Android RAW10 format: 202 * 203 * This format is exposed outside of the camera HAL to applications. 204 * 205 * RAW10 is a single-channel, 10-bit per pixel, densely packed, unprocessed 206 * format, representing raw Bayer-pattern images coming from an image sensor. 207 * 208 * In an image buffer with this format, starting from the first pixel, each 4 209 * consecutive pixels are packed into 5 bytes (40 bits). Each one of the first 210 * 4 bytes contains the top 8 bits of each pixel, The fifth byte contains the 211 * 2 least significant bits of the 4 pixels, the exact layout data for each 4 212 * consecutive pixels is illustrated below (Pi[j] stands for the jth bit of 213 * the ith pixel): 214 * 215 * bit 7 bit 0 216 * =====|=====|=====|=====|=====|=====|=====|=====| 217 * Byte 0: |P0[9]|P0[8]|P0[7]|P0[6]|P0[5]|P0[4]|P0[3]|P0[2]| 218 * |-----|-----|-----|-----|-----|-----|-----|-----| 219 * Byte 1: |P1[9]|P1[8]|P1[7]|P1[6]|P1[5]|P1[4]|P1[3]|P1[2]| 220 * |-----|-----|-----|-----|-----|-----|-----|-----| 221 * Byte 2: |P2[9]|P2[8]|P2[7]|P2[6]|P2[5]|P2[4]|P2[3]|P2[2]| 222 * |-----|-----|-----|-----|-----|-----|-----|-----| 223 * Byte 3: |P3[9]|P3[8]|P3[7]|P3[6]|P3[5]|P3[4]|P3[3]|P3[2]| 224 * |-----|-----|-----|-----|-----|-----|-----|-----| 225 * Byte 4: |P3[1]|P3[0]|P2[1]|P2[0]|P1[1]|P1[0]|P0[1]|P0[0]| 226 * =============================================== 227 * 228 * This format assumes 229 * - a width multiple of 4 pixels 230 * - an even height 231 * - a horizontal stride equal to the width 232 * - a vertical stride equal to the height 233 * - strides are specified in pixels, not in bytes 234 * 235 * size = stride * height * 10 / 8 236 * 237 * This format must be accepted by the gralloc module when used with the 238 * following usage flags: 239 * - GRALLOC_USAGE_HW_CAMERA_* 240 * - GRALLOC_USAGE_SW_* 241 * - GRALLOC_USAGE_RENDERSCRIPT 242 */ 243 HAL_PIXEL_FORMAT_RAW10 = 0x25, 244 245 /* 246 * Android opaque RAW format: 247 * 248 * This format is exposed outside of the camera HAL to applications. 249 * 250 * RAW_OPAQUE is a format for unprocessed raw image buffers coming from an 251 * image sensor. The actual structure of buffers of this format is 252 * implementation-dependent. 253 * 254 * This format must be accepted by the gralloc module when used with the 255 * following usage flags: 256 * - GRALLOC_USAGE_HW_CAMERA_* 257 * - GRALLOC_USAGE_SW_* 258 * - GRALLOC_USAGE_RENDERSCRIPT 259 */ 260 HAL_PIXEL_FORMAT_RAW_OPAQUE = 0x24, 261 262 /* 263 * Android binary blob graphics buffer format: 264 * 265 * This format is used to carry task-specific data which does not have a 266 * standard image structure. The details of the format are left to the two 267 * endpoints. 268 * 269 * A typical use case is for transporting JPEG-compressed images from the 270 * Camera HAL to the framework or to applications. 271 * 272 * Buffers of this format must have a height of 1, and width equal to their 273 * size in bytes. 274 */ 275 HAL_PIXEL_FORMAT_BLOB = 0x21, 276 277 /* 278 * Android format indicating that the choice of format is entirely up to the 279 * device-specific Gralloc implementation. 280 * 281 * The Gralloc implementation should examine the usage bits passed in when 282 * allocating a buffer with this format, and it should derive the pixel 283 * format from those usage flags. This format will never be used with any 284 * of the GRALLOC_USAGE_SW_* usage flags. 285 * 286 * If a buffer of this format is to be used as an OpenGL ES texture, the 287 * framework will assume that sampling the texture will always return an 288 * alpha value of 1.0 (i.e. the buffer contains only opaque pixel values). 289 * 290 */ 291 HAL_PIXEL_FORMAT_IMPLEMENTATION_DEFINED = 0x22, 292 293 /* 294 * Android flexible YCbCr formats 295 * 296 * This format allows platforms to use an efficient YCbCr/YCrCb buffer 297 * layout, while still describing the buffer layout in a way accessible to 298 * the CPU in a device-independent manner. While called YCbCr, it can be 299 * used to describe formats with either chromatic ordering, as well as 300 * whole planar or semiplanar layouts. 301 * 302 * struct android_ycbcr (below) is the the struct used to describe it. 303 * 304 * This format must be accepted by the gralloc module when 305 * USAGE_HW_CAMERA_WRITE and USAGE_SW_READ_* are set. 306 * 307 * This format is locked for use by gralloc's (*lock_ycbcr) method, and 308 * locking with the (*lock) method will return an error. 309 */ 310 HAL_PIXEL_FORMAT_YCbCr_420_888 = 0x23, 311 312 /* Legacy formats (deprecated), used by ImageFormat.java */ 313 HAL_PIXEL_FORMAT_YCbCr_422_SP = 0x10, // NV16 314 HAL_PIXEL_FORMAT_YCrCb_420_SP = 0x11, // NV21 315 HAL_PIXEL_FORMAT_YCbCr_422_I = 0x14, // YUY2 316}; 317 318/* 319 * Structure for describing YCbCr formats for consumption by applications. 320 * This is used with HAL_PIXEL_FORMAT_YCbCr_*_888. 321 * 322 * Buffer chroma subsampling is defined in the format. 323 * e.g. HAL_PIXEL_FORMAT_YCbCr_420_888 has subsampling 4:2:0. 324 * 325 * Buffers must have a 8 bit depth. 326 * 327 * @y, @cb, and @cr point to the first byte of their respective planes. 328 * 329 * Stride describes the distance in bytes from the first value of one row of 330 * the image to the first value of the next row. It includes the width of the 331 * image plus padding. 332 * @ystride is the stride of the luma plane. 333 * @cstride is the stride of the chroma planes. 334 * 335 * @chroma_step is the distance in bytes from one chroma pixel value to the 336 * next. This is 2 bytes for semiplanar (because chroma values are interleaved 337 * and each chroma value is one byte) and 1 for planar. 338 */ 339 340struct android_ycbcr { 341 void *y; 342 void *cb; 343 void *cr; 344 size_t ystride; 345 size_t cstride; 346 size_t chroma_step; 347 348 /** reserved for future use, set to 0 by gralloc's (*lock_ycbcr)() */ 349 uint32_t reserved[8]; 350}; 351 352/** 353 * Transformation definitions 354 * 355 * IMPORTANT NOTE: 356 * HAL_TRANSFORM_ROT_90 is applied CLOCKWISE and AFTER HAL_TRANSFORM_FLIP_{H|V}. 357 * 358 */ 359 360enum { 361 /* flip source image horizontally (around the vertical axis) */ 362 HAL_TRANSFORM_FLIP_H = 0x01, 363 /* flip source image vertically (around the horizontal axis)*/ 364 HAL_TRANSFORM_FLIP_V = 0x02, 365 /* rotate source image 90 degrees clockwise */ 366 HAL_TRANSFORM_ROT_90 = 0x04, 367 /* rotate source image 180 degrees */ 368 HAL_TRANSFORM_ROT_180 = 0x03, 369 /* rotate source image 270 degrees clockwise */ 370 HAL_TRANSFORM_ROT_270 = 0x07, 371 /* don't use. see system/window.h */ 372 HAL_TRANSFORM_RESERVED = 0x08, 373}; 374 375/** 376 * Colorspace Definitions 377 * ====================== 378 * 379 * Colorspace is the definition of how pixel values should be interpreted. 380 * It includes primaries (including white point) and the transfer 381 * characteristic function, which describes both gamma curve and numeric 382 * range (within the bit depth). 383 */ 384 385enum { 386 /* 387 * Arbitrary colorspace with manually defined characteristics. 388 * Colorspace definition must be communicated separately. 389 * 390 * This is used when specifying primaries, transfer characteristics, 391 * etc. separately. 392 * 393 * A typical use case is in video encoding parameters (e.g. for H.264), 394 * where a colorspace can have separately defined primaries, transfer 395 * characteristics, etc. 396 */ 397 HAL_COLORSPACE_ARBITRARY = 0x1, 398 399 /* 400 * YCbCr Colorspaces 401 * ----------------- 402 * 403 * Primaries are given using (x,y) coordinates in the CIE 1931 definition 404 * of x and y specified by ISO 11664-1. 405 * 406 * Transfer characteristics are the opto-electronic transfer characteristic 407 * at the source as a function of linear optical intensity (luminance). 408 */ 409 410 /* 411 * JPEG File Interchange Format (JFIF) 412 * 413 * Same model as BT.601-625, but all values (Y, Cb, Cr) range from 0 to 255 414 * 415 * Transfer characteristic curve: 416 * E = 1.099 * L ^ 0.45 - 0.099, 1.00 >= L >= 0.018 417 * E = 4.500 L, 0.018 > L >= 0 418 * L - luminance of image 0 <= L <= 1 for conventional colorimetry 419 * E - corresponding electrical signal 420 * 421 * Primaries: x y 422 * green 0.290 0.600 423 * blue 0.150 0.060 424 * red 0.640 0.330 425 * white (D65) 0.3127 0.3290 426 */ 427 HAL_COLORSPACE_JFIF = 0x101, 428 429 /* 430 * ITU-R Recommendation 601 (BT.601) - 625-line 431 * 432 * Standard-definition television, 625 Lines (PAL) 433 * 434 * For 8-bit-depth formats: 435 * Luma (Y) samples should range from 16 to 235, inclusive 436 * Chroma (Cb, Cr) samples should range from 16 to 240, inclusive 437 * 438 * For 10-bit-depth formats: 439 * Luma (Y) samples should range from 64 to 940, inclusive 440 * Chroma (Cb, Cr) samples should range from 64 to 960, inclusive 441 * 442 * Transfer characteristic curve: 443 * E = 1.099 * L ^ 0.45 - 0.099, 1.00 >= L >= 0.018 444 * E = 4.500 L, 0.018 > L >= 0 445 * L - luminance of image 0 <= L <= 1 for conventional colorimetry 446 * E - corresponding electrical signal 447 * 448 * Primaries: x y 449 * green 0.290 0.600 450 * blue 0.150 0.060 451 * red 0.640 0.330 452 * white (D65) 0.3127 0.3290 453 */ 454 HAL_COLORSPACE_BT601_625 = 0x102, 455 456 /* 457 * ITU-R Recommendation 601 (BT.601) - 525-line 458 * 459 * Standard-definition television, 525 Lines (NTSC) 460 * 461 * For 8-bit-depth formats: 462 * Luma (Y) samples should range from 16 to 235, inclusive 463 * Chroma (Cb, Cr) samples should range from 16 to 240, inclusive 464 * 465 * For 10-bit-depth formats: 466 * Luma (Y) samples should range from 64 to 940, inclusive 467 * Chroma (Cb, Cr) samples should range from 64 to 960, inclusive 468 * 469 * Transfer characteristic curve: 470 * E = 1.099 * L ^ 0.45 - 0.099, 1.00 >= L >= 0.018 471 * E = 4.500 L, 0.018 > L >= 0 472 * L - luminance of image 0 <= L <= 1 for conventional colorimetry 473 * E - corresponding electrical signal 474 * 475 * Primaries: x y 476 * green 0.310 0.595 477 * blue 0.155 0.070 478 * red 0.630 0.340 479 * white (D65) 0.3127 0.3290 480 */ 481 HAL_COLORSPACE_BT601_525 = 0x103, 482 483 /* 484 * ITU-R Recommendation 709 (BT.709) 485 * 486 * High-definition television 487 * 488 * For 8-bit-depth formats: 489 * Luma (Y) samples should range from 16 to 235, inclusive 490 * Chroma (Cb, Cr) samples should range from 16 to 240, inclusive 491 * 492 * For 10-bit-depth formats: 493 * Luma (Y) samples should range from 64 to 940, inclusive 494 * Chroma (Cb, Cr) samples should range from 64 to 960, inclusive 495 * 496 * Primaries: x y 497 * green 0.300 0.600 498 * blue 0.150 0.060 499 * red 0.640 0.330 500 * white (D65) 0.3127 0.3290 501 */ 502 HAL_COLORSPACE_BT709 = 0x104, 503}; 504 505#ifdef __cplusplus 506} 507#endif 508 509#endif /* SYSTEM_CORE_INCLUDE_ANDROID_GRAPHICS_H */ 510