include/android_stub/android/hardware_buffer.h

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