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