1 /*
2 * Copyright 2017 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 /**
18 * @file hardware_buffer.h
19 * @brief API for native hardware buffers.
20 */
21 /**
22 * @defgroup AHardwareBuffer Native Hardware Buffer
23 *
24 * AHardwareBuffer objects represent chunks of memory that can be
25 * accessed by various hardware components in the system. It can be
26 * easily converted to the Java counterpart
27 * android.hardware.HardwareBuffer and passed between processes using
28 * Binder. All operations involving AHardwareBuffer and HardwareBuffer
29 * are zero-copy, i.e., passing AHardwareBuffer to another process
30 * creates a shared view of the same region of memory.
31 *
32 * AHardwareBuffers can be bound to EGL/OpenGL and Vulkan primitives.
33 * For EGL, use the extension function eglGetNativeClientBufferANDROID
34 * to obtain an EGLClientBuffer and pass it directly to
35 * eglCreateImageKHR. Refer to the EGL extensions
36 * EGL_ANDROID_get_native_client_buffer and
37 * EGL_ANDROID_image_native_buffer for more information. In Vulkan,
38 * the contents of the AHardwareBuffer can be accessed as external
39 * memory. See the VK_ANDROID_external_memory_android_hardware_buffer
40 * extension for details.
41 *
42 * @{
43 */
44
45 #ifndef ANDROID_HARDWARE_BUFFER_H
46 #define ANDROID_HARDWARE_BUFFER_H
47
48 #include <inttypes.h>
49
50 #include <android/rect.h>
51 /**
52 * Buffer pixel formats.
53 */
54 enum AHardwareBuffer_Format {
55 /**
56 * Corresponding formats:
57 * Vulkan: VK_FORMAT_R8G8B8A8_UNORM
58 * OpenGL ES: GL_RGBA8
59 */
60 AHARDWAREBUFFER_FORMAT_R8G8B8A8_UNORM = 1,
61
62 /**
63 * 32 bits per pixel, 8 bits per channel format where alpha values are
64 * ignored (always opaque).
65 * Corresponding formats:
66 * Vulkan: VK_FORMAT_R8G8B8A8_UNORM
67 * OpenGL ES: GL_RGB8
68 */
69 AHARDWAREBUFFER_FORMAT_R8G8B8X8_UNORM = 2,
70
71 /**
72 * Corresponding formats:
73 * Vulkan: VK_FORMAT_R8G8B8_UNORM
74 * OpenGL ES: GL_RGB8
75 */
76 AHARDWAREBUFFER_FORMAT_R8G8B8_UNORM = 3,
77
78 /**
79 * Corresponding formats:
80 * Vulkan: VK_FORMAT_R5G6B5_UNORM_PACK16
81 * OpenGL ES: GL_RGB565
82 */
83 AHARDWAREBUFFER_FORMAT_R5G6B5_UNORM = 4,
84
85 /**
86 * Corresponding formats:
87 * Vulkan: VK_FORMAT_R16G16B16A16_SFLOAT
88 * OpenGL ES: GL_RGBA16F
89 */
90 AHARDWAREBUFFER_FORMAT_R16G16B16A16_FLOAT = 0x16,
91
92 /**
93 * Corresponding formats:
94 * Vulkan: VK_FORMAT_A2B10G10R10_UNORM_PACK32
95 * OpenGL ES: GL_RGB10_A2
96 */
97 AHARDWAREBUFFER_FORMAT_R10G10B10A2_UNORM = 0x2b,
98
99 /**
100 * Opaque binary blob format.
101 * Must have height 1 and one layer, with width equal to the buffer
102 * size in bytes. Corresponds to Vulkan buffers and OpenGL buffer
103 * objects. Can be bound to the latter using GL_EXT_external_buffer.
104 */
105 AHARDWAREBUFFER_FORMAT_BLOB = 0x21,
106
107 /**
108 * Corresponding formats:
109 * Vulkan: VK_FORMAT_D16_UNORM
110 * OpenGL ES: GL_DEPTH_COMPONENT16
111 */
112 AHARDWAREBUFFER_FORMAT_D16_UNORM = 0x30,
113
114 /**
115 * Corresponding formats:
116 * Vulkan: VK_FORMAT_X8_D24_UNORM_PACK32
117 * OpenGL ES: GL_DEPTH_COMPONENT24
118 */
119 AHARDWAREBUFFER_FORMAT_D24_UNORM = 0x31,
120
121 /**
122 * Corresponding formats:
123 * Vulkan: VK_FORMAT_D24_UNORM_S8_UINT
124 * OpenGL ES: GL_DEPTH24_STENCIL8
125 */
126 AHARDWAREBUFFER_FORMAT_D24_UNORM_S8_UINT = 0x32,
127
128 /**
129 * Corresponding formats:
130 * Vulkan: VK_FORMAT_D32_SFLOAT
131 * OpenGL ES: GL_DEPTH_COMPONENT32F
132 */
133 AHARDWAREBUFFER_FORMAT_D32_FLOAT = 0x33,
134
135 /**
136 * Corresponding formats:
137 * Vulkan: VK_FORMAT_D32_SFLOAT_S8_UINT
138 * OpenGL ES: GL_DEPTH32F_STENCIL8
139 */
140 AHARDWAREBUFFER_FORMAT_D32_FLOAT_S8_UINT = 0x34,
141
142 /**
143 * Corresponding formats:
144 * Vulkan: VK_FORMAT_S8_UINT
145 * OpenGL ES: GL_STENCIL_INDEX8
146 */
147 AHARDWAREBUFFER_FORMAT_S8_UINT = 0x35,
148
149 /**
150 * YUV 420 888 format.
151 * Must have an even width and height. Can be accessed in OpenGL
152 * shaders through an external sampler. Does not support mip-maps
153 * cube-maps or multi-layered textures.
154 */
155 AHARDWAREBUFFER_FORMAT_Y8Cb8Cr8_420 = 0x23,
156 };
157
158 /**
159 * Buffer usage flags, specifying how the buffer will be accessed.
160 */
161 enum AHardwareBuffer_UsageFlags {
162 /// The buffer will never be locked for direct CPU reads using the
163 /// AHardwareBuffer_lock() function. Note that reading the buffer
164 /// using OpenGL or Vulkan functions or memory mappings is still
165 /// allowed.
166 AHARDWAREBUFFER_USAGE_CPU_READ_NEVER = 0UL,
167 /// The buffer will sometimes be locked for direct CPU reads using
168 /// the AHardwareBuffer_lock() function. Note that reading the
169 /// buffer using OpenGL or Vulkan functions or memory mappings
170 /// does not require the presence of this flag.
171 AHARDWAREBUFFER_USAGE_CPU_READ_RARELY = 2UL,
172 /// The buffer will often be locked for direct CPU reads using
173 /// the AHardwareBuffer_lock() function. Note that reading the
174 /// buffer using OpenGL or Vulkan functions or memory mappings
175 /// does not require the presence of this flag.
176 AHARDWAREBUFFER_USAGE_CPU_READ_OFTEN = 3UL,
177 /// CPU read value mask.
178 AHARDWAREBUFFER_USAGE_CPU_READ_MASK = 0xFUL,
179
180 /// The buffer will never be locked for direct CPU writes using the
181 /// AHardwareBuffer_lock() function. Note that writing the buffer
182 /// using OpenGL or Vulkan functions or memory mappings is still
183 /// allowed.
184 AHARDWAREBUFFER_USAGE_CPU_WRITE_NEVER = 0UL << 4,
185 /// The buffer will sometimes be locked for direct CPU writes using
186 /// the AHardwareBuffer_lock() function. Note that writing the
187 /// buffer using OpenGL or Vulkan functions or memory mappings
188 /// does not require the presence of this flag.
189 AHARDWAREBUFFER_USAGE_CPU_WRITE_RARELY = 2UL << 4,
190 /// The buffer will often be locked for direct CPU writes using
191 /// the AHardwareBuffer_lock() function. Note that writing the
192 /// buffer using OpenGL or Vulkan functions or memory mappings
193 /// does not require the presence of this flag.
194 AHARDWAREBUFFER_USAGE_CPU_WRITE_OFTEN = 3UL << 4,
195 /// CPU write value mask.
196 AHARDWAREBUFFER_USAGE_CPU_WRITE_MASK = 0xFUL << 4,
197
198 /// The buffer will be read from by the GPU as a texture.
199 AHARDWAREBUFFER_USAGE_GPU_SAMPLED_IMAGE = 1UL << 8,
200 /// The buffer will be written to by the GPU as a framebuffer attachment.
201 AHARDWAREBUFFER_USAGE_GPU_FRAMEBUFFER = 1UL << 9,
202 /**
203 * The buffer will be written to by the GPU as a framebuffer
204 * attachment.
205 *
206 * Note that the name of this flag is somewhat misleading: it does
207 * not imply that the buffer contains a color format. A buffer with
208 * depth or stencil format that will be used as a framebuffer
209 * attachment should also have this flag. Use the equivalent flag
210 * AHARDWAREBUFFER_USAGE_GPU_FRAMEBUFFER to avoid this confusion.
211 */
212 AHARDWAREBUFFER_USAGE_GPU_COLOR_OUTPUT = AHARDWAREBUFFER_USAGE_GPU_FRAMEBUFFER,
213 /**
214 * The buffer will be used as a composer HAL overlay layer.
215 *
216 * This flag is currently only needed when using ASurfaceTransaction_setBuffer
217 * to set a buffer. In all other cases, the framework adds this flag
218 * internally to buffers that could be presented in a composer overlay.
219 * ASurfaceTransaction_setBuffer is special because it uses buffers allocated
220 * directly through AHardwareBuffer_allocate instead of buffers allocated
221 * by the framework.
222 */
223 AHARDWAREBUFFER_USAGE_COMPOSER_OVERLAY = 1ULL << 11,
224 /**
225 * The buffer is protected from direct CPU access or being read by
226 * non-secure hardware, such as video encoders.
227 *
228 * This flag is incompatible with CPU read and write flags. It is
229 * mainly used when handling DRM video. Refer to the EGL extension
230 * EGL_EXT_protected_content and GL extension
231 * GL_EXT_protected_textures for more information on how these
232 * buffers are expected to behave.
233 */
234 AHARDWAREBUFFER_USAGE_PROTECTED_CONTENT = 1UL << 14,
235 /// The buffer will be read by a hardware video encoder.
236 AHARDWAREBUFFER_USAGE_VIDEO_ENCODE = 1UL << 16,
237 /**
238 * The buffer will be used for direct writes from sensors.
239 * When this flag is present, the format must be AHARDWAREBUFFER_FORMAT_BLOB.
240 */
241 AHARDWAREBUFFER_USAGE_SENSOR_DIRECT_DATA = 1UL << 23,
242 /**
243 * The buffer will be used as a shader storage or uniform buffer object.
244 * When this flag is present, the format must be AHARDWAREBUFFER_FORMAT_BLOB.
245 */
246 AHARDWAREBUFFER_USAGE_GPU_DATA_BUFFER = 1UL << 24,
247 /**
248 * The buffer will be used as a cube map texture.
249 * When this flag is present, the buffer must have a layer count
250 * that is a multiple of 6. Note that buffers with this flag must be
251 * bound to OpenGL textures using the extension
252 * GL_EXT_EGL_image_storage instead of GL_KHR_EGL_image.
253 */
254 AHARDWAREBUFFER_USAGE_GPU_CUBE_MAP = 1UL << 25,
255 /**
256 * The buffer contains a complete mipmap hierarchy.
257 * Note that buffers with this flag must be bound to OpenGL textures using
258 * the extension GL_EXT_EGL_image_storage instead of GL_KHR_EGL_image.
259 */
260 AHARDWAREBUFFER_USAGE_GPU_MIPMAP_COMPLETE = 1UL << 26,
261
262 AHARDWAREBUFFER_USAGE_VENDOR_0 = 1ULL << 28,
263 AHARDWAREBUFFER_USAGE_VENDOR_1 = 1ULL << 29,
264 AHARDWAREBUFFER_USAGE_VENDOR_2 = 1ULL << 30,
265 AHARDWAREBUFFER_USAGE_VENDOR_3 = 1ULL << 31,
266 AHARDWAREBUFFER_USAGE_VENDOR_4 = 1ULL << 48,
267 AHARDWAREBUFFER_USAGE_VENDOR_5 = 1ULL << 49,
268 AHARDWAREBUFFER_USAGE_VENDOR_6 = 1ULL << 50,
269 AHARDWAREBUFFER_USAGE_VENDOR_7 = 1ULL << 51,
270 AHARDWAREBUFFER_USAGE_VENDOR_8 = 1ULL << 52,
271 AHARDWAREBUFFER_USAGE_VENDOR_9 = 1ULL << 53,
272 AHARDWAREBUFFER_USAGE_VENDOR_10 = 1ULL << 54,
273 AHARDWAREBUFFER_USAGE_VENDOR_11 = 1ULL << 55,
274 AHARDWAREBUFFER_USAGE_VENDOR_12 = 1ULL << 56,
275 AHARDWAREBUFFER_USAGE_VENDOR_13 = 1ULL << 57,
276 AHARDWAREBUFFER_USAGE_VENDOR_14 = 1ULL << 58,
277 AHARDWAREBUFFER_USAGE_VENDOR_15 = 1ULL << 59,
278 AHARDWAREBUFFER_USAGE_VENDOR_16 = 1ULL << 60,
279 AHARDWAREBUFFER_USAGE_VENDOR_17 = 1ULL << 61,
280 AHARDWAREBUFFER_USAGE_VENDOR_18 = 1ULL << 62,
281 AHARDWAREBUFFER_USAGE_VENDOR_19 = 1ULL << 63,
282 };
283
284 /**
285 * Buffer description. Used for allocating new buffers and querying
286 * parameters of existing ones.
287 */
288 typedef struct AHardwareBuffer_Desc {
289 uint32_t width; ///< Width in pixels.
290 uint32_t height; ///< Height in pixels.
291 /**
292 * Number of images in an image array. AHardwareBuffers with one
293 * layer correspond to regular 2D textures. AHardwareBuffers with
294 * more than layer correspond to texture arrays. If the layer count
295 * is a multiple of 6 and the usage flag
296 * AHARDWAREBUFFER_USAGE_GPU_CUBE_MAP is present, the buffer is
297 * a cube map or a cube map array.
298 */
299 uint32_t layers;
300 uint32_t format; ///< One of AHardwareBuffer_Format.
301 uint64_t usage; ///< Combination of AHardwareBuffer_UsageFlags.
302 uint32_t stride; ///< Row stride in pixels, ignored for AHardwareBuffer_allocate()
303 uint32_t rfu0; ///< Initialize to zero, reserved for future use.
304 uint64_t rfu1; ///< Initialize to zero, reserved for future use.
305 } AHardwareBuffer_Desc;
306
307 /**
308 * Holds data for a single image plane.
309 */
310 typedef struct AHardwareBuffer_Plane {
311 void* data; ///< Points to first byte in plane
312 uint32_t pixelStride; ///< Distance in bytes from the color channel of one pixel to the next
313 uint32_t rowStride; ///< Distance in bytes from the first value of one row of the image to
314 /// the first value of the next row.
315 } AHardwareBuffer_Plane;
316
317 /**
318 * Holds all image planes that contain the pixel data.
319 */
320 typedef struct AHardwareBuffer_Planes {
321 uint32_t planeCount; ///< Number of distinct planes
322 AHardwareBuffer_Plane planes[4]; ///< Array of image planes
323 } AHardwareBuffer_Planes;
324
325 /**
326 * Opaque handle for a native hardware buffer.
327 */
328 typedef struct AHardwareBuffer AHardwareBuffer;
329
330 /**
331 * Allocates a buffer that matches the passed AHardwareBuffer_Desc.
332 *
333 * If allocation succeeds, the buffer can be used according to the
334 * usage flags specified in its description. If a buffer is used in ways
335 * not compatible with its usage flags, the results are undefined and
336 * may include program termination.
337 *
338 * Available since API level 26.
339 *
340 * \return 0 on success, or an error number of the allocation fails for
341 * any reason. The returned buffer has a reference count of 1.
342 */
343 int AHardwareBuffer_allocate(const AHardwareBuffer_Desc* desc,
344 AHardwareBuffer** outBuffer);
345 /**
346 * Acquire a reference on the given AHardwareBuffer object.
347 *
348 * This prevents the object from being deleted until the last reference
349 * is removed.
350 *
351 * Available since API level 26.
352 */
353 void AHardwareBuffer_acquire(AHardwareBuffer* buffer);
354
355 /**
356 * Remove a reference that was previously acquired with
357 * AHardwareBuffer_acquire() or AHardwareBuffer_allocate().
358 *
359 * Available since API level 26.
360 */
AHardwareBuffer_release(AHardwareBuffer * buffer)361 void AHardwareBuffer_release(AHardwareBuffer* buffer) { }
362
363 /**
364 * Return a description of the AHardwareBuffer in the passed
365 * AHardwareBuffer_Desc struct.
366 *
367 * Available since API level 26.
368 */
369 void AHardwareBuffer_describe(const AHardwareBuffer* buffer,
370 AHardwareBuffer_Desc* outDesc);
371
372 /**
373 * Lock the AHardwareBuffer for direct CPU access.
374 *
375 * This function can lock the buffer for either reading or writing.
376 * It may block if the hardware needs to finish rendering, if CPU caches
377 * need to be synchronized, or possibly for other implementation-
378 * specific reasons.
379 *
380 * The passed AHardwareBuffer must have one layer, otherwise the call
381 * will fail.
382 *
383 * If \a fence is not negative, it specifies a fence file descriptor on
384 * which to wait before locking the buffer. If it's negative, the caller
385 * is responsible for ensuring that writes to the buffer have completed
386 * before calling this function. Using this parameter is more efficient
387 * than waiting on the fence and then calling this function.
388 *
389 * The \a usage parameter may only specify AHARDWAREBUFFER_USAGE_CPU_*.
390 * If set, then outVirtualAddress is filled with the address of the
391 * buffer in virtual memory. The flags must also be compatible with
392 * usage flags specified at buffer creation: if a read flag is passed,
393 * the buffer must have been created with
394 * AHARDWAREBUFFER_USAGE_CPU_READ_RARELY or
395 * AHARDWAREBUFFER_USAGE_CPU_READ_OFTEN. If a write flag is passed, it
396 * must have been created with AHARDWAREBUFFER_USAGE_CPU_WRITE_RARELY or
397 * AHARDWAREBUFFER_USAGE_CPU_WRITE_OFTEN.
398 *
399 * If \a rect is not NULL, the caller promises to modify only data in
400 * the area specified by rect. If rect is NULL, the caller may modify
401 * the contents of the entire buffer. The content of the buffer outside
402 * of the specified rect is NOT modified by this call.
403 *
404 * It is legal for several different threads to lock a buffer for read
405 * access; none of the threads are blocked.
406 *
407 * Locking a buffer simultaneously for write or read/write is undefined,
408 * but will neither terminate the process nor block the caller.
409 * AHardwareBuffer_lock may return an error or leave the buffer's
410 * content in an indeterminate state.
411 *
412 * If the buffer has AHARDWAREBUFFER_FORMAT_BLOB, it is legal lock it
413 * for reading and writing in multiple threads and/or processes
414 * simultaneously, and the contents of the buffer behave like shared
415 * memory.
416 *
417 * Available since API level 26.
418 *
419 * \return 0 on success. -EINVAL if \a buffer is NULL, the usage flags
420 * are not a combination of AHARDWAREBUFFER_USAGE_CPU_*, or the buffer
421 * has more than one layer. Error number if the lock fails for any other
422 * reason.
423 */
424 int AHardwareBuffer_lock(AHardwareBuffer* buffer, uint64_t usage,
425 int32_t fence, const ARect* rect, void** outVirtualAddress);
426
427 /**
428 * Lock a potentially multi-planar AHardwareBuffer for direct CPU access.
429 *
430 * This function is similar to AHardwareBuffer_lock, but can lock multi-planar
431 * formats. The locked planes are returned in the \a outPlanes argument. Note,
432 * that multi-planar should not be confused with multi-layer images, which this
433 * locking function does not support.
434 *
435 * YUV formats are always represented by three separate planes of data, one for
436 * each color plane. The order of planes in the array is guaranteed such that
437 * plane #0 is always Y, plane #1 is always U (Cb), and plane #2 is always V
438 * (Cr). All other formats are represented by a single plane.
439 *
440 * Additional information always accompanies the buffers, describing the row
441 * stride and the pixel stride for each plane.
442 *
443 * In case the buffer cannot be locked, \a outPlanes will contain zero planes.
444 *
445 * See the AHardwareBuffer_lock documentation for all other locking semantics.
446 *
447 * Available since API level 29.
448 *
449 * \return 0 on success. -EINVAL if \a buffer is NULL, the usage flags
450 * are not a combination of AHARDWAREBUFFER_USAGE_CPU_*, or the buffer
451 * has more than one layer. Error number if the lock fails for any other
452 * reason.
453 */
454 int AHardwareBuffer_lockPlanes(AHardwareBuffer* buffer, uint64_t usage,
455 int32_t fence, const ARect* rect, AHardwareBuffer_Planes* outPlanes);
456
457 /**
458 * Unlock the AHardwareBuffer from direct CPU access.
459 *
460 * Must be called after all changes to the buffer are completed by the
461 * caller. If \a fence is NULL, the function will block until all work
462 * is completed. Otherwise, \a fence will be set either to a valid file
463 * descriptor or to -1. The file descriptor will become signaled once
464 * the unlocking is complete and buffer contents are updated.
465 * The caller is responsible for closing the file descriptor once it's
466 * no longer needed. The value -1 indicates that unlocking has already
467 * completed before the function returned and no further operations are
468 * necessary.
469 *
470 * Available since API level 26.
471 *
472 * \return 0 on success. -EINVAL if \a buffer is NULL. Error number if
473 * the unlock fails for any reason.
474 */
475 int AHardwareBuffer_unlock(AHardwareBuffer* buffer, int32_t* fence);
476
477 /**
478 * Send the AHardwareBuffer to an AF_UNIX socket.
479 *
480 * Available since API level 26.
481 *
482 * \return 0 on success, -EINVAL if \a buffer is NULL, or an error
483 * number if the operation fails for any reason.
484 */
485 int AHardwareBuffer_sendHandleToUnixSocket(const AHardwareBuffer* buffer, int socketFd);
486
487 /**
488 * Receive an AHardwareBuffer from an AF_UNIX socket.
489 *
490 * Available since API level 26.
491 *
492 * \return 0 on success, -EINVAL if \a outBuffer is NULL, or an error
493 * number if the operation fails for any reason.
494 */
495 int AHardwareBuffer_recvHandleFromUnixSocket(int socketFd, AHardwareBuffer** outBuffer);
496
497 /**
498 * Test whether the given format and usage flag combination is
499 * allocatable.
500 *
501 * If this function returns true, it means that a buffer with the given
502 * description can be allocated on this implementation, unless resource
503 * exhaustion occurs. If this function returns false, it means that the
504 * allocation of the given description will never succeed.
505 *
506 * The return value of this function may depend on all fields in the
507 * description, except stride, which is always ignored. For example,
508 * some implementations have implementation-defined limits on texture
509 * size and layer count.
510 *
511 * Available since API level 29.
512 *
513 * \return 1 if the format and usage flag combination is allocatable,
514 * 0 otherwise.
515 */
516 int AHardwareBuffer_isSupported(const AHardwareBuffer_Desc* desc);
517
518 /**
519 * Lock an AHardwareBuffer for direct CPU access.
520 *
521 * This function is the same as the above lock function, but passes back
522 * additional information about the bytes per pixel and the bytes per stride
523 * of the locked buffer. If the bytes per pixel or bytes per stride are unknown
524 * or variable, or if the underlying mapper implementation does not support returning
525 * additional information, then this call will fail with INVALID_OPERATION
526 *
527 * Available since API level 29.
528 */
529 int AHardwareBuffer_lockAndGetInfo(AHardwareBuffer* buffer, uint64_t usage,
530 int32_t fence, const ARect* rect, void** outVirtualAddress,
531 int32_t* outBytesPerPixel, int32_t* outBytesPerStride);
532
533 #endif // ANDROID_HARDWARE_BUFFER_H
534
535 /** @} */
536