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