1 /* 2 * Copyright 2015 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 ANDROID_HARDWARE_GRALLOC1_H 18 #define ANDROID_HARDWARE_GRALLOC1_H 19 20 #include <hardware/hardware.h> 21 #include <system/window.h> 22 23 __BEGIN_DECLS 24 25 #define GRALLOC_MODULE_API_VERSION_1_0 HARDWARE_MODULE_API_VERSION(1, 0) 26 #define GRALLOC_HARDWARE_MODULE_ID "gralloc" 27 28 /* 29 * Enums 30 */ 31 32 typedef enum { 33 GRALLOC1_CAPABILITY_INVALID = 0, 34 35 /* If this capability is supported, then the outBuffers parameter to 36 * allocate may be NULL, which instructs the device to report whether the 37 * given allocation is possible or not. */ 38 GRALLOC1_CAPABILITY_TEST_ALLOCATE = 1, 39 GRALLOC1_LAST_CAPABILITY = 1, 40 } gralloc1_capability_t; 41 42 typedef enum { 43 GRALLOC1_CONSUMER_USAGE_NONE = 0, 44 GRALLOC1_CONSUMER_USAGE_CPU_READ_NEVER = 0, 45 /* 1ULL << 0 */ 46 GRALLOC1_CONSUMER_USAGE_CPU_READ = 1ULL << 1, 47 GRALLOC1_CONSUMER_USAGE_CPU_READ_OFTEN = 1ULL << 2 | 48 GRALLOC1_CONSUMER_USAGE_CPU_READ, 49 /* 1ULL << 3 */ 50 /* 1ULL << 4 */ 51 /* 1ULL << 5 */ 52 /* 1ULL << 6 */ 53 /* 1ULL << 7 */ 54 GRALLOC1_CONSUMER_USAGE_GPU_TEXTURE = 1ULL << 8, 55 /* 1ULL << 9 */ 56 /* 1ULL << 10 */ 57 GRALLOC1_CONSUMER_USAGE_HWCOMPOSER = 1ULL << 11, 58 GRALLOC1_CONSUMER_USAGE_CLIENT_TARGET = 1ULL << 12, 59 /* 1ULL << 13 */ 60 /* 1ULL << 14 */ 61 GRALLOC1_CONSUMER_USAGE_CURSOR = 1ULL << 15, 62 GRALLOC1_CONSUMER_USAGE_VIDEO_ENCODER = 1ULL << 16, 63 /* 1ULL << 17 */ 64 GRALLOC1_CONSUMER_USAGE_CAMERA = 1ULL << 18, 65 /* 1ULL << 19 */ 66 GRALLOC1_CONSUMER_USAGE_RENDERSCRIPT = 1ULL << 20, 67 68 /* Indicates that the consumer may attach buffers to their end of the 69 * BufferQueue, which means that the producer may never have seen a given 70 * dequeued buffer before. May be ignored by the gralloc device. */ 71 GRALLOC1_CONSUMER_USAGE_FOREIGN_BUFFERS = 1ULL << 21, 72 73 /* 1ULL << 22 */ 74 /* 1ULL << 23 */ 75 /* 1ULL << 24 */ 76 /* 1ULL << 25 */ 77 /* 1ULL << 26 */ 78 /* 1ULL << 27 */ 79 80 /* Bits reserved for implementation-specific usage flags */ 81 GRALLOC1_CONSUMER_USAGE_PRIVATE_0 = 1ULL << 28, 82 GRALLOC1_CONSUMER_USAGE_PRIVATE_1 = 1ULL << 29, 83 GRALLOC1_CONSUMER_USAGE_PRIVATE_2 = 1ULL << 30, 84 GRALLOC1_CONSUMER_USAGE_PRIVATE_3 = 1ULL << 31, 85 86 /* 1ULL << 32 */ 87 /* 1ULL << 33 */ 88 /* 1ULL << 34 */ 89 /* 1ULL << 35 */ 90 /* 1ULL << 36 */ 91 /* 1ULL << 37 */ 92 /* 1ULL << 38 */ 93 /* 1ULL << 39 */ 94 /* 1ULL << 40 */ 95 /* 1ULL << 41 */ 96 /* 1ULL << 42 */ 97 /* 1ULL << 43 */ 98 /* 1ULL << 44 */ 99 /* 1ULL << 45 */ 100 /* 1ULL << 46 */ 101 /* 1ULL << 47 */ 102 103 /* Bits reserved for implementation-specific usage flags */ 104 GRALLOC1_CONSUMER_USAGE_PRIVATE_19 = 1ULL << 48, 105 GRALLOC1_CONSUMER_USAGE_PRIVATE_18 = 1ULL << 49, 106 GRALLOC1_CONSUMER_USAGE_PRIVATE_17 = 1ULL << 50, 107 GRALLOC1_CONSUMER_USAGE_PRIVATE_16 = 1ULL << 51, 108 GRALLOC1_CONSUMER_USAGE_PRIVATE_15 = 1ULL << 52, 109 GRALLOC1_CONSUMER_USAGE_PRIVATE_14 = 1ULL << 53, 110 GRALLOC1_CONSUMER_USAGE_PRIVATE_13 = 1ULL << 54, 111 GRALLOC1_CONSUMER_USAGE_PRIVATE_12 = 1ULL << 55, 112 GRALLOC1_CONSUMER_USAGE_PRIVATE_11 = 1ULL << 56, 113 GRALLOC1_CONSUMER_USAGE_PRIVATE_10 = 1ULL << 57, 114 GRALLOC1_CONSUMER_USAGE_PRIVATE_9 = 1ULL << 58, 115 GRALLOC1_CONSUMER_USAGE_PRIVATE_8 = 1ULL << 59, 116 GRALLOC1_CONSUMER_USAGE_PRIVATE_7 = 1ULL << 60, 117 GRALLOC1_CONSUMER_USAGE_PRIVATE_6 = 1ULL << 61, 118 GRALLOC1_CONSUMER_USAGE_PRIVATE_5 = 1ULL << 62, 119 GRALLOC1_CONSUMER_USAGE_PRIVATE_4 = 1ULL << 63, 120 } gralloc1_consumer_usage_t; 121 122 typedef enum { 123 GRALLOC1_FUNCTION_INVALID = 0, 124 GRALLOC1_FUNCTION_DUMP = 1, 125 GRALLOC1_FUNCTION_CREATE_DESCRIPTOR = 2, 126 GRALLOC1_FUNCTION_DESTROY_DESCRIPTOR = 3, 127 GRALLOC1_FUNCTION_SET_CONSUMER_USAGE = 4, 128 GRALLOC1_FUNCTION_SET_DIMENSIONS = 5, 129 GRALLOC1_FUNCTION_SET_FORMAT = 6, 130 GRALLOC1_FUNCTION_SET_PRODUCER_USAGE = 7, 131 GRALLOC1_FUNCTION_GET_BACKING_STORE = 8, 132 GRALLOC1_FUNCTION_GET_CONSUMER_USAGE = 9, 133 GRALLOC1_FUNCTION_GET_DIMENSIONS = 10, 134 GRALLOC1_FUNCTION_GET_FORMAT = 11, 135 GRALLOC1_FUNCTION_GET_PRODUCER_USAGE = 12, 136 GRALLOC1_FUNCTION_GET_STRIDE = 13, 137 GRALLOC1_FUNCTION_ALLOCATE = 14, 138 GRALLOC1_FUNCTION_RETAIN = 15, 139 GRALLOC1_FUNCTION_RELEASE = 16, 140 GRALLOC1_FUNCTION_GET_NUM_FLEX_PLANES = 17, 141 GRALLOC1_FUNCTION_LOCK = 18, 142 GRALLOC1_FUNCTION_LOCK_FLEX = 19, 143 GRALLOC1_FUNCTION_UNLOCK = 20, 144 GRALLOC1_LAST_FUNCTION = 20, 145 } gralloc1_function_descriptor_t; 146 147 typedef enum { 148 GRALLOC1_ERROR_NONE = 0, 149 GRALLOC1_ERROR_BAD_DESCRIPTOR = 1, 150 GRALLOC1_ERROR_BAD_HANDLE = 2, 151 GRALLOC1_ERROR_BAD_VALUE = 3, 152 GRALLOC1_ERROR_NOT_SHARED = 4, 153 GRALLOC1_ERROR_NO_RESOURCES = 5, 154 GRALLOC1_ERROR_UNDEFINED = 6, 155 GRALLOC1_ERROR_UNSUPPORTED = 7, 156 } gralloc1_error_t; 157 158 typedef enum { 159 GRALLOC1_PRODUCER_USAGE_NONE = 0, 160 GRALLOC1_PRODUCER_USAGE_CPU_WRITE_NEVER = 0, 161 /* 1ULL << 0 */ 162 GRALLOC1_PRODUCER_USAGE_CPU_READ = 1ULL << 1, 163 GRALLOC1_PRODUCER_USAGE_CPU_READ_OFTEN = 1ULL << 2 | 164 GRALLOC1_PRODUCER_USAGE_CPU_READ, 165 /* 1ULL << 3 */ 166 /* 1ULL << 4 */ 167 GRALLOC1_PRODUCER_USAGE_CPU_WRITE = 1ULL << 5, 168 GRALLOC1_PRODUCER_USAGE_CPU_WRITE_OFTEN = 1ULL << 6 | 169 GRALLOC1_PRODUCER_USAGE_CPU_WRITE, 170 /* 1ULL << 7 */ 171 /* 1ULL << 8 */ 172 GRALLOC1_PRODUCER_USAGE_GPU_RENDER_TARGET = 1ULL << 9, 173 /* 1ULL << 10 */ 174 /* 1ULL << 11 */ 175 /* 1ULL << 12 */ 176 /* 1ULL << 13 */ 177 178 /* The consumer must have a hardware-protected path to an external display 179 * sink for this buffer. If a hardware-protected path is not available, then 180 * do not attempt to display this buffer. */ 181 GRALLOC1_PRODUCER_USAGE_PROTECTED = 1ULL << 14, 182 183 /* 1ULL << 15 */ 184 /* 1ULL << 16 */ 185 GRALLOC1_PRODUCER_USAGE_CAMERA = 1ULL << 17, 186 /* 1ULL << 18 */ 187 /* 1ULL << 19 */ 188 /* 1ULL << 20 */ 189 /* 1ULL << 21 */ 190 GRALLOC1_PRODUCER_USAGE_VIDEO_DECODER = 1ULL << 22, 191 /* 1ULL << 23 */ 192 /* 1ULL << 24 */ 193 /* 1ULL << 25 */ 194 /* 1ULL << 26 */ 195 /* 1ULL << 27 */ 196 197 /* Bits reserved for implementation-specific usage flags */ 198 GRALLOC1_PRODUCER_USAGE_PRIVATE_0 = 1ULL << 28, 199 GRALLOC1_PRODUCER_USAGE_PRIVATE_1 = 1ULL << 29, 200 GRALLOC1_PRODUCER_USAGE_PRIVATE_2 = 1ULL << 30, 201 GRALLOC1_PRODUCER_USAGE_PRIVATE_3 = 1ULL << 31, 202 203 /* 1ULL << 32 */ 204 /* 1ULL << 33 */ 205 /* 1ULL << 34 */ 206 /* 1ULL << 35 */ 207 /* 1ULL << 36 */ 208 /* 1ULL << 37 */ 209 /* 1ULL << 38 */ 210 /* 1ULL << 39 */ 211 /* 1ULL << 40 */ 212 /* 1ULL << 41 */ 213 /* 1ULL << 42 */ 214 /* 1ULL << 43 */ 215 /* 1ULL << 44 */ 216 /* 1ULL << 45 */ 217 /* 1ULL << 46 */ 218 /* 1ULL << 47 */ 219 220 /* Bits reserved for implementation-specific usage flags */ 221 GRALLOC1_PRODUCER_USAGE_PRIVATE_19 = 1ULL << 48, 222 GRALLOC1_PRODUCER_USAGE_PRIVATE_18 = 1ULL << 49, 223 GRALLOC1_PRODUCER_USAGE_PRIVATE_17 = 1ULL << 50, 224 GRALLOC1_PRODUCER_USAGE_PRIVATE_16 = 1ULL << 51, 225 GRALLOC1_PRODUCER_USAGE_PRIVATE_15 = 1ULL << 52, 226 GRALLOC1_PRODUCER_USAGE_PRIVATE_14 = 1ULL << 53, 227 GRALLOC1_PRODUCER_USAGE_PRIVATE_13 = 1ULL << 54, 228 GRALLOC1_PRODUCER_USAGE_PRIVATE_12 = 1ULL << 55, 229 GRALLOC1_PRODUCER_USAGE_PRIVATE_11 = 1ULL << 56, 230 GRALLOC1_PRODUCER_USAGE_PRIVATE_10 = 1ULL << 57, 231 GRALLOC1_PRODUCER_USAGE_PRIVATE_9 = 1ULL << 58, 232 GRALLOC1_PRODUCER_USAGE_PRIVATE_8 = 1ULL << 59, 233 GRALLOC1_PRODUCER_USAGE_PRIVATE_7 = 1ULL << 60, 234 GRALLOC1_PRODUCER_USAGE_PRIVATE_6 = 1ULL << 61, 235 GRALLOC1_PRODUCER_USAGE_PRIVATE_5 = 1ULL << 62, 236 GRALLOC1_PRODUCER_USAGE_PRIVATE_4 = 1ULL << 63, 237 } gralloc1_producer_usage_t; 238 239 /* 240 * Typedefs 241 */ 242 243 typedef void (*gralloc1_function_pointer_t)(); 244 245 typedef uint64_t gralloc1_backing_store_t; 246 typedef uint64_t gralloc1_buffer_descriptor_t; 247 248 /* 249 * Device Struct 250 */ 251 252 typedef struct gralloc1_device { 253 /* Must be the first member of this struct, since a pointer to this struct 254 * will be generated by casting from a hw_device_t* */ 255 struct hw_device_t common; 256 257 /* getCapabilities(..., outCount, outCapabilities) 258 * 259 * Provides a list of capabilities (described in the definition of 260 * gralloc1_capability_t above) supported by this device. This list must not 261 * change after the device has been loaded. 262 * 263 * Parameters: 264 * outCount - if outCapabilities was NULL, the number of capabilities 265 * which would have been returned; if outCapabilities was not NULL, 266 * the number of capabilities returned, which must not exceed the 267 * value stored in outCount prior to the call 268 * outCapabilities - a list of capabilities supported by this device; may 269 * be NULL, in which case this function must write into outCount the 270 * number of capabilities which would have been written into 271 * outCapabilities 272 */ 273 void (*getCapabilities)(struct gralloc1_device* device, uint32_t* outCount, 274 int32_t* /*gralloc1_capability_t*/ outCapabilities); 275 276 /* getFunction(..., descriptor) 277 * 278 * Returns a function pointer which implements the requested description. 279 * 280 * Parameters: 281 * descriptor - the function to return 282 * 283 * Returns either a function pointer implementing the requested descriptor 284 * or NULL if the described function is not supported by this device. 285 */ 286 gralloc1_function_pointer_t (*getFunction)(struct gralloc1_device* device, 287 int32_t /*gralloc1_function_descriptor_t*/ descriptor); 288 } gralloc1_device_t; 289 290 static inline int gralloc1_open(const struct hw_module_t* module, 291 gralloc1_device_t** device) { 292 return module->methods->open(module, GRALLOC_HARDWARE_MODULE_ID, 293 (struct hw_device_t**) device); 294 } 295 296 static inline int gralloc1_close(gralloc1_device_t* device) { 297 return device->common.close(&device->common); 298 } 299 300 /* dump(..., outSize, outBuffer) 301 * Function descriptor: GRALLOC1_FUNCTION_DUMP 302 * Must be provided by all gralloc1 devices 303 * 304 * Retrieves implementation-defined debug information, which will be displayed 305 * during, for example, `dumpsys SurfaceFlinger`. 306 * 307 * If called with outBuffer == NULL, the device should store a copy of the 308 * desired output and return its length in bytes in outSize. If the device 309 * already has a stored copy, that copy should be purged and replaced with a 310 * fresh copy. 311 * 312 * If called with outBuffer != NULL, the device should copy its stored version 313 * of the output into outBuffer and store how many bytes of data it copied into 314 * outSize. Prior to this call, the client will have populated outSize with the 315 * maximum number of bytes outBuffer can hold. The device must not write more 316 * than this amount into outBuffer. If the device does not currently have a 317 * stored copy, then it should return 0 in outSize. 318 * 319 * Any data written into outBuffer need not be null-terminated. 320 * 321 * Parameters: 322 * outSize - if outBuffer was NULL, the number of bytes needed to copy the 323 * device's stored output; if outBuffer was not NULL, the number of bytes 324 * written into it, which must not exceed the value stored in outSize 325 * prior to the call; pointer will be non-NULL 326 * outBuffer - the buffer to write the dump output into; may be NULL as 327 * described above; data written into this buffer need not be 328 * null-terminated 329 */ 330 typedef void (*GRALLOC1_PFN_DUMP)(gralloc1_device_t* device, uint32_t* outSize, 331 char* outBuffer); 332 333 /* 334 * Buffer descriptor lifecycle functions 335 * 336 * All of these functions take as their first parameter a device pointer, so 337 * this parameter is omitted from the described parameter lists. 338 */ 339 340 /* createDescriptor(..., outDescriptor) 341 * Function descriptor: GRALLOC1_FUNCTION_CREATE_DESCRIPTOR 342 * Must be provided by all gralloc1 devices 343 * 344 * Creates a new, empty buffer descriptor. 345 * 346 * Parameters: 347 * outDescriptor - the new buffer descriptor 348 * 349 * Returns GRALLOC1_ERROR_NONE or one of the following errors: 350 * GRALLOC1_ERROR_NO_RESOURCES - no more descriptors can currently be created 351 */ 352 typedef int32_t /*gralloc1_error_t*/ (*GRALLOC1_PFN_CREATE_DESCRIPTOR)( 353 gralloc1_device_t* device, gralloc1_buffer_descriptor_t* outDescriptor); 354 355 /* destroyDescriptor(..., descriptor) 356 * Function descriptor: GRALLOC1_FUNCTION_DESTROY_DESCRIPTOR 357 * Must be provided by all gralloc1 devices 358 * 359 * Destroys an existing buffer descriptor. 360 * 361 * Parameters: 362 * descriptor - the buffer descriptor to destroy 363 * 364 * Returns GRALLOC1_ERROR_NONE or one of the following errors: 365 * GRALLOC1_ERROR_BAD_DESCRIPTOR - descriptor does not refer to a valid 366 * buffer descriptor 367 */ 368 typedef int32_t /*gralloc1_error_t*/ (*GRALLOC1_PFN_DESTROY_DESCRIPTOR)( 369 gralloc1_device_t* device, gralloc1_buffer_descriptor_t descriptor); 370 371 /* 372 * Buffer descriptor modification functions 373 * 374 * All of these functions take as their first two parameters a device pointer 375 * and a buffer descriptor, so these parameters are omitted from the described 376 * parameter lists. 377 */ 378 379 /* setConsumerUsage(..., usage) 380 * Function descriptor: GRALLOC1_FUNCTION_SET_CONSUMER_USAGE 381 * Must be provided by all gralloc1 devices 382 * 383 * Sets the desired consumer usage flags of the buffer. 384 * 385 * Valid usage flags can be found in the definition of gralloc1_consumer_usage_t 386 * above. 387 * 388 * Parameters: 389 * usage - the desired consumer usage flags 390 * 391 * Returns GRALLOC1_ERROR_NONE or one of the following errors: 392 * GRALLOC1_ERROR_BAD_DESCRIPTOR - the buffer descriptor is invalid 393 * GRALLOC1_ERROR_BAD_VALUE - an invalid usage flag was passed in 394 */ 395 typedef int32_t /*gralloc1_error_t*/ (*GRALLOC1_PFN_SET_CONSUMER_USAGE)( 396 gralloc1_device_t* device, gralloc1_buffer_descriptor_t descriptor, 397 uint64_t /*gralloc1_consumer_usage_t*/ usage); 398 399 /* setDimensions(..., width, height) 400 * Function descriptor: GRALLOC1_FUNCTION_SET_DIMENSIONS 401 * Must be provided by all gralloc1 devices 402 * 403 * Sets the desired width and height of the buffer in pixels. 404 * 405 * The width specifies how many columns of pixels should be in the allocated 406 * buffer, but does not necessarily represent the offset in columns between the 407 * same column in adjacent rows. If this offset is required, consult getStride 408 * below. 409 * 410 * The height specifies how many rows of pixels should be in the allocated 411 * buffer. 412 * 413 * Parameters: 414 * width - the desired width in pixels 415 * height - the desired height in pixels 416 * 417 * Returns GRALLOC1_ERROR_NONE or one of the following errors: 418 * GRALLOC1_ERROR_BAD_DESCRIPTOR - the buffer descriptor is invalid 419 */ 420 typedef int32_t /*gralloc1_error_t*/ (*GRALLOC1_PFN_SET_DIMENSIONS)( 421 gralloc1_device_t* device, gralloc1_buffer_descriptor_t descriptor, 422 uint32_t width, uint32_t height); 423 424 /* setFormat(..., format) 425 * Function descriptor: GRALLOC1_FUNCTION_SET_FORMAT 426 * Must be provided by all gralloc1 devices 427 * 428 * Sets the desired format of the buffer. 429 * 430 * The valid formats can be found in <system/graphics.h>. 431 * 432 * Parameters: 433 * format - the desired format 434 * 435 * Returns GRALLOC1_ERROR_NONE or one of the following errors: 436 * GRALLOC1_ERROR_BAD_DESCRIPTOR - the buffer descriptor is invalid 437 * GRALLOC1_ERROR_BAD_VALUE - format is invalid 438 */ 439 typedef int32_t /*gralloc1_error_t*/ (*GRALLOC1_PFN_SET_FORMAT)( 440 gralloc1_device_t* device, gralloc1_buffer_descriptor_t descriptor, 441 int32_t /*android_pixel_format_t*/ format); 442 443 /* setProducerUsage(..., usage) 444 * Function descriptor: GRALLOC1_FUNCTION_SET_PRODUCER_USAGE 445 * Must be provided by all gralloc1 devices 446 * 447 * Sets the desired producer usage flags of the buffer. 448 * 449 * Valid usage flags can be found in the definition of gralloc1_producer_usage_t 450 * above. 451 * 452 * Parameters: 453 * usage - the desired producer usage flags 454 * 455 * Returns GRALLOC1_ERROR_NONE or one of the following errors: 456 * GRALLOC1_ERROR_BAD_DESCRIPTOR - the buffer descriptor is invalid 457 * GRALLOC1_ERROR_BAD_VALUE - an invalid usage flag was passed in 458 */ 459 typedef int32_t /*gralloc1_error_t*/ (*GRALLOC1_PFN_SET_PRODUCER_USAGE)( 460 gralloc1_device_t* device, gralloc1_buffer_descriptor_t descriptor, 461 uint64_t /*gralloc1_producer_usage_t*/ usage); 462 463 /* 464 * Buffer handle query functions 465 * 466 * All of these functions take as their first two parameters a device pointer 467 * and a buffer handle, so these parameters are omitted from the described 468 * parameter lists. 469 * 470 * [1] Currently many of these functions may return GRALLOC1_ERROR_UNSUPPORTED, 471 * which means that the device is not able to retrieve the requested information 472 * from the buffer. This is necessary to enable a smooth transition from earlier 473 * versions of the gralloc HAL, but gralloc1 implementers are strongly 474 * discouraged from returning this value, as future versions of the platform 475 * code will require all of these functions to succeed given a valid handle. 476 */ 477 478 /* getBackingStore(..., outStore) 479 * Function descriptor: GRALLOC1_FUNCTION_GET_BACKING_STORE 480 * Must be provided by all gralloc1 devices 481 * 482 * Gets a value that uniquely identifies the backing store of the given buffer. 483 * 484 * Buffers which share a backing store should return the same value from this 485 * function. If the buffer is present in more than one process, the backing 486 * store value for that buffer is not required to be the same in every process. 487 * 488 * Parameters: 489 * outStore - the backing store identifier for this buffer 490 * 491 * Returns GRALLOC1_ERROR_NONE or one of the following errors: 492 * GRALLOC1_ERROR_BAD_HANDLE - the buffer handle is invalid 493 * GRALLOC1_ERROR_UNSUPPORTED - the device is unable to retrieve the 494 * backing store identifier from the buffer; see note [1] in this 495 * section's header for more information 496 */ 497 typedef int32_t /*gralloc1_error_t*/ (*GRALLOC1_PFN_GET_BACKING_STORE)( 498 gralloc1_device_t* device, buffer_handle_t buffer, 499 gralloc1_backing_store_t* outStore); 500 501 /* getConsumerUsage(..., outUsage) 502 * Function descriptor: GRALLOC1_FUNCTION_GET_CONSUMER_USAGE 503 * Must be provided by all gralloc1 devices 504 * 505 * Gets the consumer usage flags which were used to allocate this buffer. 506 * 507 * Usage flags can be found in the definition of gralloc1_consumer_usage_t above 508 * 509 * Parameters: 510 * outUsage - the consumer usage flags used to allocate this buffer; must be 511 * non-NULL 512 * 513 * Returns GRALLOC1_ERROR_NONE or one of the following errors: 514 * GRALLOC1_ERROR_BAD_HANDLE - the buffer handle is invalid 515 * GRALLOC1_ERROR_UNSUPPORTED - the device is unable to retrieve the 516 * dimensions from the buffer; see note [1] in this section's header for 517 * more information 518 */ 519 typedef int32_t /*gralloc1_error_t*/ (*GRALLOC1_PFN_GET_CONSUMER_USAGE)( 520 gralloc1_device_t* device, buffer_handle_t buffer, 521 uint64_t* /*gralloc1_consumer_usage_t*/ outUsage); 522 523 /* getDimensions(..., outWidth, outHeight) 524 * Function descriptor: GRALLOC1_FUNCTION_GET_DIMENSIONS 525 * Must be provided by all gralloc1 devices 526 * 527 * Gets the width and height of the buffer in pixels. 528 * 529 * See setDimensions for more information about these values. 530 * 531 * Parameters: 532 * outWidth - the width of the buffer in pixels, must be non-NULL 533 * outHeight - the height of the buffer in pixels, must be non-NULL 534 * 535 * Returns GRALLOC1_ERROR_NONE or one of the following errors: 536 * GRALLOC1_ERROR_BAD_HANDLE - the buffer handle is invalid 537 * GRALLOC1_ERROR_UNSUPPORTED - the device is unable to retrieve the 538 * dimensions from the buffer; see note [1] in this section's header for 539 * more information 540 */ 541 typedef int32_t /*gralloc1_error_t*/ (*GRALLOC1_PFN_GET_DIMENSIONS)( 542 gralloc1_device_t* device, buffer_handle_t buffer, uint32_t* outWidth, 543 uint32_t* outHeight); 544 545 /* getFormat(..., outFormat) 546 * Function descriptor: GRALLOC1_FUNCTION_GET_FORMAT 547 * Must be provided by all gralloc1 devices 548 * 549 * Gets the format of the buffer. 550 * 551 * The valid formats can be found in the HAL_PIXEL_FORMAT_* enum in 552 * system/graphics.h. 553 * 554 * Parameters: 555 * outFormat - the format of the buffer; must be non-NULL 556 * 557 * Returns GRALLOC1_ERROR_NONE or one of the following errors: 558 * GRALLOC1_ERROR_BAD_HANDLE - the buffer handle is invalid 559 * GRALLOC1_ERROR_UNSUPPORTED - the device is unable to retrieve the format 560 * from the buffer; see note [1] in this section's header for more 561 * information 562 */ 563 typedef int32_t /*gralloc1_error_t*/ (*GRALLOC1_PFN_GET_FORMAT)( 564 gralloc1_device_t* device, buffer_handle_t descriptor, 565 int32_t* outFormat); 566 567 /* getProducerUsage(..., outUsage) 568 * Function descriptor: GRALLOC1_FUNCTION_GET_PRODUCER_USAGE 569 * Must be provided by all gralloc1 devices 570 * 571 * Gets the producer usage flags which were used to allocate this buffer. 572 * 573 * Usage flags can be found in the definition of gralloc1_producer_usage_t above 574 * 575 * Parameters: 576 * outUsage - the producer usage flags used to allocate this buffer; must be 577 * non-NULL 578 * 579 * Returns GRALLOC1_ERROR_NONE or one of the following errors: 580 * GRALLOC1_ERROR_BAD_HANDLE - the buffer handle is invalid 581 * GRALLOC1_ERROR_UNSUPPORTED - the device is unable to retrieve the usage 582 * from the buffer; see note [1] in this section's header for more 583 * information 584 */ 585 typedef int32_t /*gralloc1_error_t*/ (*GRALLOC1_PFN_GET_PRODUCER_USAGE)( 586 gralloc1_device_t* device, buffer_handle_t buffer, 587 uint64_t* /*gralloc1_producer_usage_t*/ outUsage); 588 589 /* getStride(..., outStride) 590 * Function descriptor: GRALLOC1_FUNCTION_GET_STRIDE 591 * Must be provided by all gralloc1 devices 592 * 593 * Gets the stride of the buffer in pixels. 594 * 595 * The stride is the offset in pixel-sized elements between the same column in 596 * two adjacent rows of pixels. This may not be equal to the width of the 597 * buffer. 598 * 599 * Parameters: 600 * outStride - the stride in pixels; must be non-NULL 601 * 602 * Returns GRALLOC1_ERROR_NONE or one of the following errors: 603 * GRALLOC1_ERROR_BAD_HANDLE - the buffer handle is invalid 604 * GRALLOC1_ERROR_UNDEFINED - the notion of a stride is not meaningful for 605 * this format 606 * GRALLOC1_ERROR_UNSUPPORTED - the device is unable to retrieve the stride 607 * from the descriptor; see note [1] in this section's header for more 608 * information 609 */ 610 typedef int32_t /*gralloc1_error_t*/ (*GRALLOC1_PFN_GET_STRIDE)( 611 gralloc1_device_t* device, buffer_handle_t buffer, uint32_t* outStride); 612 613 /* 614 * Buffer management functions 615 */ 616 617 /* allocate(..., numDescriptors, descriptors, outBuffers) 618 * Function descriptor: GRALLOC1_FUNCTION_ALLOCATE 619 * Must be provided by all gralloc1 devices 620 * 621 * Attempts to allocate a number of buffers sharing a backing store. 622 * 623 * Each buffer will correspond to one of the descriptors passed into the 624 * function. If the device is unable to share the backing store between the 625 * buffers, it should attempt to allocate the buffers with different backing 626 * stores and return GRALLOC1_ERROR_NOT_SHARED if it is successful. 627 * 628 * If this call is successful, the client is responsible for freeing the 629 * buffer_handle_t using release() when it is finished with the buffer. It is 630 * not necessary to call retain() on the returned buffers, as they must have a 631 * reference added by the device before returning. 632 * 633 * If GRALLOC1_CAPABILITY_TEST_ALLOCATE is supported by this device, outBuffers 634 * may be NULL. In this case, the device must not attempt to allocate any 635 * buffers, but instead must return either GRALLOC1_ERROR_NONE if such an 636 * allocation is possible (ignoring potential resource contention which might 637 * lead to a GRALLOC1_ERROR_NO_RESOURCES error), GRALLOC1_ERROR_NOT_SHARED if 638 * the buffers can be allocated, but cannot share a backing store, or 639 * GRALLOC1_ERROR_UNSUPPORTED if one or more of the descriptors can never be 640 * allocated by the device. 641 * 642 * Parameters: 643 * numDescriptors - the number of buffer descriptors, which must also be equal 644 * to the size of the outBuffers array 645 * descriptors - the buffer descriptors to attempt to allocate 646 * outBuffers - the allocated buffers; must be non-NULL unless the device 647 * supports GRALLOC1_CAPABILITY_TEST_ALLOCATE (see above), and must not be 648 * modified by the device if allocation is unsuccessful 649 * 650 * Returns GRALLOC1_ERROR_NONE or one of the following errors: 651 * GRALLOC1_ERROR_BAD_DESCRIPTOR - one of the descriptors does not refer to a 652 * valid buffer descriptor 653 * GRALLOC1_ERROR_NOT_SHARED - allocation was successful, but required more 654 * than one backing store to satisfy all of the buffer descriptors 655 * GRALLOC1_ERROR_NO_RESOURCES - allocation failed because one or more of the 656 * backing stores could not be created at this time (but this allocation 657 * might succeed at a future time) 658 * GRALLOC1_ERROR_UNSUPPORTED - one or more of the descriptors can never be 659 * satisfied by the device 660 */ 661 typedef int32_t /*gralloc1_error_t*/ (*GRALLOC1_PFN_ALLOCATE)( 662 gralloc1_device_t* device, uint32_t numDescriptors, 663 const gralloc1_buffer_descriptor_t* descriptors, 664 buffer_handle_t* outBuffers); 665 666 /* retain(..., buffer) 667 * Function descriptor: GRALLOC1_FUNCTION_RETAIN 668 * Must be provided by all gralloc1 devices 669 * 670 * Adds a reference to the given buffer. 671 * 672 * This function must be called when a buffer_handle_t is received from a remote 673 * process to prevent the buffer's data from being freed when the remote process 674 * releases the buffer. It may also be called to increase the reference count if 675 * two components in the same process want to interact with the buffer 676 * independently. 677 * 678 * Parameters: 679 * buffer - the buffer to which a reference should be added 680 * 681 * Returns GRALLOC1_ERROR_NONE or one of the following errors: 682 * GRALLOC1_ERROR_BAD_HANDLE - the buffer handle is invalid 683 * GRALLOC1_ERROR_NO_RESOURCES - it is not possible to add a reference to this 684 * buffer at this time 685 */ 686 typedef int32_t /*gralloc1_error_t*/ (*GRALLOC1_PFN_RETAIN)( 687 gralloc1_device_t* device, buffer_handle_t buffer); 688 689 /* release(..., buffer) 690 * Function descriptor: GRALLOC1_FUNCTION_RELEASE 691 * Must be provided by all gralloc1 devices 692 * 693 * Removes a reference from the given buffer. 694 * 695 * If no references remain, the buffer should be freed. When the last buffer 696 * referring to a particular backing store is freed, that backing store should 697 * also be freed. 698 * 699 * Parameters: 700 * buffer - the buffer from which a reference should be removed 701 * 702 * Returns GRALLOC1_ERROR_NONE or one of the following errors: 703 * GRALLOC1_ERROR_BAD_HANDLE - the buffer handle is invalid 704 */ 705 typedef int32_t /*gralloc1_error_t*/ (*GRALLOC1_PFN_RELEASE)( 706 gralloc1_device_t* device, buffer_handle_t buffer); 707 708 /* 709 * Buffer access functions 710 * 711 * All of these functions take as their first parameter a device pointer, so 712 * this parameter is omitted from the described parameter lists. 713 */ 714 715 typedef struct gralloc1_rect { 716 int32_t left; 717 int32_t top; 718 int32_t width; 719 int32_t height; 720 } gralloc1_rect_t; 721 722 /* getNumFlexPlanes(..., buffer, outNumPlanes) 723 * Function descriptor: GRALLOC1_FUNCTION_GET_NUM_FLEX_PLANES 724 * Must be provided by all gralloc1 devices 725 * 726 * Returns the number of flex layout planes which are needed to represent the 727 * given buffer. This may be used to efficiently allocate only as many plane 728 * structures as necessary before calling into lockFlex. 729 * 730 * If the given buffer cannot be locked as a flex format, this function may 731 * return GRALLOC1_ERROR_UNSUPPORTED (as lockFlex would). 732 * 733 * Parameters: 734 * buffer - the buffers for which the number of planes should be queried 735 * outNumPlanes - the number of flex planes required to describe the given 736 * buffer; must be non-NULL 737 * 738 * Returns GRALLOC1_ERROR_NONE or one of the following errors: 739 * GRALLOC1_ERROR_BAD_HANDLE - the buffer handle is invalid 740 * GRALLOC1_ERROR_UNSUPPORTED - the buffer's format cannot be represented in a 741 * flex layout 742 */ 743 typedef int32_t /*gralloc1_error_t*/ (*GRALLOC1_PFN_GET_NUM_FLEX_PLANES)( 744 gralloc1_device_t* device, buffer_handle_t buffer, 745 uint32_t* outNumPlanes); 746 747 /* lock(..., buffer, producerUsage, consumerUsage, accessRegion, outData, 748 * acquireFence) 749 * Function descriptor: GRALLOC1_FUNCTION_LOCK 750 * Must be provided by all gralloc1 devices 751 * 752 * Locks the given buffer for the specified CPU usage. 753 * 754 * Exactly one of producerUsage and consumerUsage must be *_USAGE_NONE. The 755 * usage which is not *_USAGE_NONE must be one of the *_USAGE_CPU_* values, as 756 * applicable. Locking a buffer for a non-CPU usage is not supported. 757 * 758 * Locking the same buffer simultaneously from multiple threads is permitted, 759 * but if any of the threads attempt to lock the buffer for writing, the 760 * behavior is undefined, except that it must not cause process termination or 761 * block the client indefinitely. Leaving the buffer content in an indeterminate 762 * state or returning an error are both acceptable. 763 * 764 * The client must not modify the content of the buffer outside of accessRegion, 765 * and the device need not guarantee that content outside of accessRegion is 766 * valid for reading. The result of reading or writing outside of accessRegion 767 * is undefined, except that it must not cause process termination. 768 * 769 * outData must be a non-NULL pointer, the contents of which which will be 770 * filled with a pointer to the locked buffer memory. This address will 771 * represent the top-left corner of the entire buffer, even if accessRegion does 772 * not begin at the top-left corner. 773 * 774 * acquireFence is a file descriptor referring to a acquire sync fence object, 775 * which will be signaled when it is safe for the device to access the contents 776 * of the buffer (prior to locking). If it is already safe to access the buffer 777 * contents, -1 may be passed instead. 778 * 779 * Parameters: 780 * buffer - the buffer to lock 781 * producerUsage - the producer usage flags to request; either this or 782 * consumerUsage must be GRALLOC1_*_USAGE_NONE, and the other must be a 783 * CPU usage 784 * consumerUsage - the consumer usage flags to request; either this or 785 * producerUsage must be GRALLOC1_*_USAGE_NONE, and the other must be a 786 * CPU usage 787 * accessRegion - the portion of the buffer that the client intends to access; 788 * must be non-NULL 789 * outData - will be filled with a CPU-accessible pointer to the buffer data; 790 * must be non-NULL 791 * acquireFence - a sync fence file descriptor as described above 792 * 793 * Returns GRALLOC1_ERROR_NONE or one of the following errors: 794 * GRALLOC1_ERROR_BAD_HANDLE - the buffer handle is invalid 795 * GRALLOC1_ERROR_BAD_VALUE - neither or both of producerUsage and 796 * consumerUsage were GRALLOC1_*_USAGE_NONE, or the usage which was not 797 * *_USAGE_NONE was not a CPU usage 798 * GRALLOC1_ERROR_NO_RESOURCES - the buffer cannot be locked at this time, but 799 * locking may succeed at a future time 800 * GRALLOC1_ERROR_UNSUPPORTED - the buffer cannot be locked with the given 801 * usage, and any future attempts at locking will also fail 802 */ 803 typedef int32_t /*gralloc1_error_t*/ (*GRALLOC1_PFN_LOCK)( 804 gralloc1_device_t* device, buffer_handle_t buffer, 805 uint64_t /*gralloc1_producer_usage_t*/ producerUsage, 806 uint64_t /*gralloc1_consumer_usage_t*/ consumerUsage, 807 const gralloc1_rect_t* accessRegion, void** outData, 808 int32_t acquireFence); 809 810 /* lockFlex(..., buffer, producerUsage, consumerUsage, accessRegion, 811 * outFlexLayout, outAcquireFence) 812 * Function descriptor: GRALLOC1_FUNCTION_LOCK_FLEX 813 * Must be provided by all gralloc1 devices 814 * 815 * This is largely the same as lock(), except that instead of returning a 816 * pointer directly to the buffer data, it returns an android_flex_layout 817 * struct describing how to access the data planes. 818 * 819 * This function must work on buffers with HAL_PIXEL_FORMAT_YCbCr_*_888 if 820 * supported by the device, as well as with any other formats requested by 821 * multimedia codecs when they are configured with a flexible-YUV-compatible 822 * color format. 823 * 824 * This function may also be called on buffers of other formats, including 825 * non-YUV formats, but if the buffer format is not compatible with a flexible 826 * representation, it may return GRALLOC1_ERROR_UNSUPPORTED. 827 * 828 * Parameters: 829 * buffer - the buffer to lock 830 * producerUsage - the producer usage flags to request; either this or 831 * consumerUsage must be GRALLOC1_*_USAGE_NONE, and the other must be a 832 * CPU usage 833 * consumerUsage - the consumer usage flags to request; either this or 834 * producerUsage must be GRALLOC1_*_USAGE_NONE, and the other must be a 835 * CPU usage 836 * accessRegion - the portion of the buffer that the client intends to access; 837 * must be non-NULL 838 * outFlexLayout - will be filled with the description of the planes in the 839 * buffer 840 * acquireFence - a sync fence file descriptor as described in lock() 841 * 842 * Returns GRALLOC1_ERROR_NONE or one of the following errors: 843 * GRALLOC1_ERROR_BAD_HANDLE - the buffer handle is invalid 844 * GRALLOC1_ERROR_BAD_VALUE - neither or both of producerUsage and 845 * consumerUsage were *_USAGE_NONE, or the usage which was not 846 * *_USAGE_NONE was not a CPU usage 847 * GRALLOC1_ERROR_NO_RESOURCES - the buffer cannot be locked at this time, but 848 * locking may succeed at a future time 849 * GRALLOC1_ERROR_UNSUPPORTED - the buffer cannot be locked with the given 850 * usage, and any future attempts at locking will also fail 851 */ 852 typedef int32_t /*gralloc1_error_t*/ (*GRALLOC1_PFN_LOCK_FLEX)( 853 gralloc1_device_t* device, buffer_handle_t buffer, 854 uint64_t /*gralloc1_producer_usage_t*/ producerUsage, 855 uint64_t /*gralloc1_consumer_usage_t*/ consumerUsage, 856 const gralloc1_rect_t* accessRegion, 857 struct android_flex_layout* outFlexLayout, int32_t acquireFence); 858 859 /* unlock(..., buffer, releaseFence) 860 * Function descriptor: GRALLOC1_FUNCTION_UNLOCK 861 * Must be provided by all gralloc1 devices 862 * 863 * This function indicates to the device that the client will be done with the 864 * buffer when releaseFence signals. 865 * 866 * outReleaseFence will be filled with a file descriptor referring to a release 867 * sync fence object, which will be signaled when it is safe to access the 868 * contents of the buffer (after the buffer has been unlocked). If it is already 869 * safe to access the buffer contents, then -1 may be returned instead. 870 * 871 * This function is used to unlock both buffers locked by lock() and those 872 * locked by lockFlex(). 873 * 874 * Parameters: 875 * buffer - the buffer to unlock 876 * outReleaseFence - a sync fence file descriptor as described above 877 * 878 * Returns GRALLOC1_ERROR_NONE or one of the following errors: 879 * GRALLOC1_ERROR_BAD_HANDLE - the buffer handle is invalid 880 */ 881 typedef int32_t /*gralloc1_error_t*/ (*GRALLOC1_PFN_UNLOCK)( 882 gralloc1_device_t* device, buffer_handle_t buffer, 883 int32_t* outReleaseFence); 884 885 __END_DECLS 886 887 #endif 888
