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