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