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
gralloc1_open(const struct hw_module_t * module,gralloc1_device_t ** device)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
gralloc1_close(gralloc1_device_t * device)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 *
679 * Get the transport size of a buffer. An imported buffer handle is a raw
680 * buffer handle with the process-local runtime data appended. This
681 * function, for example, allows a caller to omit the process-local
682 * runtime data at the tail when serializing the imported buffer handle.
683 *
684 * Note that a client might or might not omit the process-local runtime
685 * data when sending an imported buffer handle. The mapper must support
686 * both cases on the receiving end.
687 *
688 * Parameters:
689 * outNumFds - the number of file descriptors needed for transport
690 * outNumInts - the number of integers needed for transport
691 *
692 * Returns GRALLOC1_ERROR_NONE or one of the following errors:
693 * GRALLOC1_ERROR_BAD_HANDLE - the buffer handle is invalid
694 * GRALLOC1_ERROR_UNSUPPORTED - the device is unable to retrieve the numFds
695 * and numInts; see note [1] in this section's header for more information
696 */
697 typedef int32_t /*gralloc1_error_t*/ (*GRALLOC1_PFN_GET_TRANSPORT_SIZE)(
698 gralloc1_device_t* device, buffer_handle_t buffer, uint32_t *outNumFds,
699 uint32_t *outNumInts);
700
701 typedef struct gralloc1_buffer_descriptor_info {
702 uint32_t width;
703 uint32_t height;
704 uint32_t layerCount;
705 int32_t /*android_pixel_format_t*/ format;
706 uint64_t producerUsage;
707 uint64_t consumerUsage;
708 } gralloc1_buffer_descriptor_info_t;
709
710 /* validateBufferSize(..., )
711 * Function descriptor: GRALLOC1_FUNCTION_VALIDATE_BUFFER_SIZE
712 *
713 * Validate that the buffer can be safely accessed by a caller who assumes
714 * the specified descriptorInfo and stride. This must at least validate
715 * that the buffer size is large enough. Validating the buffer against
716 * individual buffer attributes is optional.
717 *
718 * Parameters:
719 * descriptor - specifies the attributes of the buffer
720 * stride - the buffer stride returned by IAllocator::allocate
721 *
722 * Returns GRALLOC1_ERROR_NONE or one of the following errors:
723 * GRALLOC1_ERROR_BAD_HANDLE - the buffer handle is invalid
724 * GRALLOC1_ERROR_BAD_VALUE - when buffer cannot be safely accessed
725 * GRALLOC1_ERROR_UNSUPPORTED - the device is unable to validate the buffer
726 * size; see note [1] in this section's header for more information
727 */
728 typedef int32_t /*gralloc1_error_t*/ (*GRALLOC1_PFN_VALIDATE_BUFFER_SIZE)(
729 gralloc1_device_t* device, buffer_handle_t buffer,
730 const gralloc1_buffer_descriptor_info_t* descriptorInfo,
731 uint32_t stride);
732
733 /*
734 * Buffer management functions
735 */
736
737 /* allocate(..., numDescriptors, descriptors, outBuffers)
738 * Function descriptor: GRALLOC1_FUNCTION_ALLOCATE
739 * Must be provided by all gralloc1 devices
740 *
741 * Attempts to allocate a number of buffers sharing a backing store.
742 *
743 * Each buffer will correspond to one of the descriptors passed into the
744 * function. If the device is unable to share the backing store between the
745 * buffers, it should attempt to allocate the buffers with different backing
746 * stores and return GRALLOC1_ERROR_NOT_SHARED if it is successful.
747 *
748 * If this call is successful, the client is responsible for freeing the
749 * buffer_handle_t using release() when it is finished with the buffer. It is
750 * not necessary to call retain() on the returned buffers, as they must have a
751 * reference added by the device before returning.
752 *
753 * If GRALLOC1_CAPABILITY_TEST_ALLOCATE is supported by this device, outBuffers
754 * may be NULL. In this case, the device must not attempt to allocate any
755 * buffers, but instead must return either GRALLOC1_ERROR_NONE if such an
756 * allocation is possible (ignoring potential resource contention which might
757 * lead to a GRALLOC1_ERROR_NO_RESOURCES error), GRALLOC1_ERROR_NOT_SHARED if
758 * the buffers can be allocated, but cannot share a backing store, or
759 * GRALLOC1_ERROR_UNSUPPORTED if one or more of the descriptors can never be
760 * allocated by the device.
761 *
762 * Parameters:
763 * numDescriptors - the number of buffer descriptors, which must also be equal
764 * to the size of the outBuffers array
765 * descriptors - the buffer descriptors to attempt to allocate
766 * outBuffers - the allocated buffers; must be non-NULL unless the device
767 * supports GRALLOC1_CAPABILITY_TEST_ALLOCATE (see above), and must not be
768 * modified by the device if allocation is unsuccessful
769 *
770 * Returns GRALLOC1_ERROR_NONE or one of the following errors:
771 * GRALLOC1_ERROR_BAD_DESCRIPTOR - one of the descriptors does not refer to a
772 * valid buffer descriptor
773 * GRALLOC1_ERROR_NOT_SHARED - allocation was successful, but required more
774 * than one backing store to satisfy all of the buffer descriptors
775 * GRALLOC1_ERROR_NO_RESOURCES - allocation failed because one or more of the
776 * backing stores could not be created at this time (but this allocation
777 * might succeed at a future time)
778 * GRALLOC1_ERROR_UNSUPPORTED - one or more of the descriptors can never be
779 * satisfied by the device
780 */
781 typedef int32_t /*gralloc1_error_t*/ (*GRALLOC1_PFN_ALLOCATE)(
782 gralloc1_device_t* device, uint32_t numDescriptors,
783 const gralloc1_buffer_descriptor_t* descriptors,
784 buffer_handle_t* outBuffers);
785
786 /* importBuffer(..., rawHandle, outBuffer);
787 * Function descriptor: GRALLOC1_FUNCTION_IMPORT_BUFFER
788 * This function is optional for all gralloc1 devices.
789 * When supported, GRALLOC1_CAPABILITY_RELEASE_IMPLY_DELETE must also be
790 * supported.
791 *
792 * Explictly imports a buffer into a proccess.
793 *
794 * This function can be called in place of retain when a raw buffer handle is
795 * received by a remote process. Import producess a import handle that can
796 * be used to access the underlying graphic buffer. The new import handle has a
797 * ref count of 1.
798 *
799 * This function must at least validate the raw handle before creating the
800 * imported handle. It must also support importing the same raw handle
801 * multiple times to create multiple imported handles. The imported handle
802 * must be considered valid everywhere in the process.
803 *
804 * Parameters:
805 * rawHandle - the raw buffer handle to import
806 * outBuffer - a handle to the newly imported buffer
807 *
808 * Returns GRALLOC1_ERROR_NONE or one of the following errors:
809 * GRALLOC1_ERROR_BAD_HANDLE - the buffer handle is invalid
810 * GRALLOC1_ERROR_NO_RESOURCES - it is not possible to add a import to this
811 * buffer at this time
812 */
813 typedef int32_t /*gralloc1_error_t*/ (*GRALLOC1_PFN_IMPORT_BUFFER)(
814 gralloc1_device_t* device, const buffer_handle_t rawHandle,
815 buffer_handle_t* outBuffer);
816
817 /* retain(..., buffer)
818 * Function descriptor: GRALLOC1_FUNCTION_RETAIN
819 * Must be provided by all gralloc1 devices
820 *
821 * Adds a reference to the given buffer.
822 *
823 * This function must be called when a buffer_handle_t is received from a remote
824 * process to prevent the buffer's data from being freed when the remote process
825 * releases the buffer. It may also be called to increase the reference count if
826 * two components in the same process want to interact with the buffer
827 * independently.
828 *
829 * Parameters:
830 * buffer - the buffer to which a reference should be added
831 *
832 * Returns GRALLOC1_ERROR_NONE or one of the following errors:
833 * GRALLOC1_ERROR_BAD_HANDLE - the buffer handle is invalid
834 * GRALLOC1_ERROR_NO_RESOURCES - it is not possible to add a reference to this
835 * buffer at this time
836 */
837 typedef int32_t /*gralloc1_error_t*/ (*GRALLOC1_PFN_RETAIN)(
838 gralloc1_device_t* device, buffer_handle_t buffer);
839
840 /* release(..., buffer)
841 * Function descriptor: GRALLOC1_FUNCTION_RELEASE
842 * Must be provided by all gralloc1 devices
843 *
844 * Removes a reference from the given buffer.
845 *
846 * If no references remain, the buffer should be freed. When the last buffer
847 * referring to a particular backing store is freed, that backing store should
848 * also be freed.
849 *
850 * When GRALLOC1_CAPABILITY_RELEASE_IMPLY_DELETE is supported,
851 * native_handle_close and native_handle_delete must always be called by the
852 * implementation whenever the last reference is removed. Otherwise, a call
853 * to release() will be followed by native_handle_close and native_handle_delete
854 * by the caller when the buffer is not allocated locally through allocate().
855 *
856 * Parameters:
857 * buffer - the buffer from which a reference should be removed
858 *
859 * Returns GRALLOC1_ERROR_NONE or one of the following errors:
860 * GRALLOC1_ERROR_BAD_HANDLE - the buffer handle is invalid
861 */
862 typedef int32_t /*gralloc1_error_t*/ (*GRALLOC1_PFN_RELEASE)(
863 gralloc1_device_t* device, buffer_handle_t buffer);
864
865 /*
866 * Buffer access functions
867 *
868 * All of these functions take as their first parameter a device pointer, so
869 * this parameter is omitted from the described parameter lists.
870 */
871
872 typedef struct gralloc1_rect {
873 int32_t left;
874 int32_t top;
875 int32_t width;
876 int32_t height;
877 } gralloc1_rect_t;
878
879 /* getNumFlexPlanes(..., buffer, outNumPlanes)
880 * Function descriptor: GRALLOC1_FUNCTION_GET_NUM_FLEX_PLANES
881 * Must be provided by all gralloc1 devices
882 *
883 * Returns the number of flex layout planes which are needed to represent the
884 * given buffer. This may be used to efficiently allocate only as many plane
885 * structures as necessary before calling into lockFlex.
886 *
887 * If the given buffer cannot be locked as a flex format, this function may
888 * return GRALLOC1_ERROR_UNSUPPORTED (as lockFlex would).
889 *
890 * Parameters:
891 * buffer - the buffers for which the number of planes should be queried
892 * outNumPlanes - the number of flex planes required to describe the given
893 * buffer; must be non-NULL
894 *
895 * Returns GRALLOC1_ERROR_NONE or one of the following errors:
896 * GRALLOC1_ERROR_BAD_HANDLE - the buffer handle is invalid
897 * GRALLOC1_ERROR_UNSUPPORTED - the buffer's format cannot be represented in a
898 * flex layout
899 */
900 typedef int32_t /*gralloc1_error_t*/ (*GRALLOC1_PFN_GET_NUM_FLEX_PLANES)(
901 gralloc1_device_t* device, buffer_handle_t buffer,
902 uint32_t* outNumPlanes);
903
904 /* lock(..., buffer, producerUsage, consumerUsage, accessRegion, outData,
905 * acquireFence)
906 * Function descriptor: GRALLOC1_FUNCTION_LOCK
907 * Must be provided by all gralloc1 devices
908 *
909 * Locks the given buffer for the specified CPU usage.
910 *
911 * Exactly one of producerUsage and consumerUsage must be *_USAGE_NONE. The
912 * usage which is not *_USAGE_NONE must be one of the *_USAGE_CPU_* values, as
913 * applicable. Locking a buffer for a non-CPU usage is not supported.
914 *
915 * Locking the same buffer simultaneously from multiple threads is permitted,
916 * but if any of the threads attempt to lock the buffer for writing, the
917 * behavior is undefined, except that it must not cause process termination or
918 * block the client indefinitely. Leaving the buffer content in an indeterminate
919 * state or returning an error are both acceptable.
920 *
921 * The client must not modify the content of the buffer outside of accessRegion,
922 * and the device need not guarantee that content outside of accessRegion is
923 * valid for reading. The result of reading or writing outside of accessRegion
924 * is undefined, except that it must not cause process termination.
925 *
926 * outData must be a non-NULL pointer, the contents of which which will be
927 * filled with a pointer to the locked buffer memory. This address will
928 * represent the top-left corner of the entire buffer, even if accessRegion does
929 * not begin at the top-left corner.
930 *
931 * acquireFence is a file descriptor referring to a acquire sync fence object,
932 * which will be signaled when it is safe for the device to access the contents
933 * of the buffer (prior to locking). If it is already safe to access the buffer
934 * contents, -1 may be passed instead.
935 *
936 * Parameters:
937 * buffer - the buffer to lock
938 * producerUsage - the producer usage flags to request; either this or
939 * consumerUsage must be GRALLOC1_*_USAGE_NONE, and the other must be a
940 * CPU usage
941 * consumerUsage - the consumer usage flags to request; either this or
942 * producerUsage must be GRALLOC1_*_USAGE_NONE, and the other must be a
943 * CPU usage
944 * accessRegion - the portion of the buffer that the client intends to access;
945 * must be non-NULL
946 * outData - will be filled with a CPU-accessible pointer to the buffer data;
947 * must be non-NULL
948 * acquireFence - a sync fence file descriptor as described above
949 *
950 * Returns GRALLOC1_ERROR_NONE or one of the following errors:
951 * GRALLOC1_ERROR_BAD_HANDLE - the buffer handle is invalid
952 * GRALLOC1_ERROR_BAD_VALUE - neither or both of producerUsage and
953 * consumerUsage were GRALLOC1_*_USAGE_NONE, or the usage which was not
954 * *_USAGE_NONE was not a CPU usage
955 * GRALLOC1_ERROR_NO_RESOURCES - the buffer cannot be locked at this time, but
956 * locking may succeed at a future time
957 * GRALLOC1_ERROR_UNSUPPORTED - the buffer cannot be locked with the given
958 * usage, and any future attempts at locking will also fail
959 */
960 typedef int32_t /*gralloc1_error_t*/ (*GRALLOC1_PFN_LOCK)(
961 gralloc1_device_t* device, buffer_handle_t buffer,
962 uint64_t /*gralloc1_producer_usage_t*/ producerUsage,
963 uint64_t /*gralloc1_consumer_usage_t*/ consumerUsage,
964 const gralloc1_rect_t* accessRegion, void** outData,
965 int32_t acquireFence);
966
967 /* lockFlex(..., buffer, producerUsage, consumerUsage, accessRegion,
968 * outFlexLayout, outAcquireFence)
969 * Function descriptor: GRALLOC1_FUNCTION_LOCK_FLEX
970 * Must be provided by all gralloc1 devices
971 *
972 * This is largely the same as lock(), except that instead of returning a
973 * pointer directly to the buffer data, it returns an android_flex_layout
974 * struct describing how to access the data planes.
975 *
976 * This function must work on buffers with HAL_PIXEL_FORMAT_YCbCr_*_888 if
977 * supported by the device, as well as with any other formats requested by
978 * multimedia codecs when they are configured with a flexible-YUV-compatible
979 * color format.
980 *
981 * This function may also be called on buffers of other formats, including
982 * non-YUV formats, but if the buffer format is not compatible with a flexible
983 * representation, it may return GRALLOC1_ERROR_UNSUPPORTED.
984 *
985 * Parameters:
986 * buffer - the buffer to lock
987 * producerUsage - the producer usage flags to request; either this or
988 * consumerUsage must be GRALLOC1_*_USAGE_NONE, and the other must be a
989 * CPU usage
990 * consumerUsage - the consumer usage flags to request; either this or
991 * producerUsage must be GRALLOC1_*_USAGE_NONE, and the other must be a
992 * CPU usage
993 * accessRegion - the portion of the buffer that the client intends to access;
994 * must be non-NULL
995 * outFlexLayout - will be filled with the description of the planes in the
996 * buffer
997 * acquireFence - a sync fence file descriptor as described in lock()
998 *
999 * Returns GRALLOC1_ERROR_NONE or one of the following errors:
1000 * GRALLOC1_ERROR_BAD_HANDLE - the buffer handle is invalid
1001 * GRALLOC1_ERROR_BAD_VALUE - neither or both of producerUsage and
1002 * consumerUsage were *_USAGE_NONE, or the usage which was not
1003 * *_USAGE_NONE was not a CPU usage
1004 * GRALLOC1_ERROR_NO_RESOURCES - the buffer cannot be locked at this time, but
1005 * locking may succeed at a future time
1006 * GRALLOC1_ERROR_UNSUPPORTED - the buffer cannot be locked with the given
1007 * usage, and any future attempts at locking will also fail
1008 */
1009 typedef int32_t /*gralloc1_error_t*/ (*GRALLOC1_PFN_LOCK_FLEX)(
1010 gralloc1_device_t* device, buffer_handle_t buffer,
1011 uint64_t /*gralloc1_producer_usage_t*/ producerUsage,
1012 uint64_t /*gralloc1_consumer_usage_t*/ consumerUsage,
1013 const gralloc1_rect_t* accessRegion,
1014 struct android_flex_layout* outFlexLayout, int32_t acquireFence);
1015
1016 /* unlock(..., buffer, releaseFence)
1017 * Function descriptor: GRALLOC1_FUNCTION_UNLOCK
1018 * Must be provided by all gralloc1 devices
1019 *
1020 * This function indicates to the device that the client will be done with the
1021 * buffer when releaseFence signals.
1022 *
1023 * outReleaseFence will be filled with a file descriptor referring to a release
1024 * sync fence object, which will be signaled when it is safe to access the
1025 * contents of the buffer (after the buffer has been unlocked). If it is already
1026 * safe to access the buffer contents, then -1 may be returned instead.
1027 *
1028 * This function is used to unlock both buffers locked by lock() and those
1029 * locked by lockFlex().
1030 *
1031 * Parameters:
1032 * buffer - the buffer to unlock
1033 * outReleaseFence - a sync fence file descriptor as described above
1034 *
1035 * Returns GRALLOC1_ERROR_NONE or one of the following errors:
1036 * GRALLOC1_ERROR_BAD_HANDLE - the buffer handle is invalid
1037 */
1038 typedef int32_t /*gralloc1_error_t*/ (*GRALLOC1_PFN_UNLOCK)(
1039 gralloc1_device_t* device, buffer_handle_t buffer,
1040 int32_t* outReleaseFence);
1041
1042 __END_DECLS
1043
1044 #endif
1045