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