frameworks/native: Fixes for AHardwareBuffer, ANativeWindow and ARect docs.
Several of the documentation comments were not being picked up by Doxygen.
Additionally, fixed a problem with an incorrect GL ES equivalent format
being listed for AHARDWAREBUFFER_FORMAT_R8G8B8X8_UNORM.
Bug: 73658203
Bug: 76172636
Bug: 76179340
Test: Not necessary, documentation-only changes.
Change-Id: Ia6bf7853e9eed5ab53616d410f8bd1a6309e47b8
diff --git a/libs/arect/include/android/rect.h b/libs/arect/include/android/rect.h
index 80741c0..b36728e 100644
--- a/libs/arect/include/android/rect.h
+++ b/libs/arect/include/android/rect.h
@@ -33,23 +33,26 @@
#endif
/**
- * {@link ARect} is a struct that represents a rectangular window area.
+ * Rectangular window area.
*
- * It is used with {@link
- * ANativeActivityCallbacks::onContentRectChanged} event callback and
- * ANativeWindow_lock() function.
+ * This is the NDK equivalent of the android.graphics.Rect class in Java. It is
+ * used with {@link ANativeActivityCallbacks::onContentRectChanged} event
+ * callback and the ANativeWindow_lock() function.
+ *
+ * In a valid ARect, left <= right and top <= bottom. ARect with left=0, top=10,
+ * right=1, bottom=11 contains only one pixel at x=0, y=10.
*/
typedef struct ARect {
#ifdef __cplusplus
typedef int32_t value_type;
#endif
- /** left position */
+ /// Minimum X coordinate of the rectangle.
int32_t left;
- /** top position */
+ /// Minimum Y coordinate of the rectangle.
int32_t top;
- /** left position */
+ /// Maximum X coordinate of the rectangle.
int32_t right;
- /** bottom position */
+ /// Maximum Y coordinate of the rectangle.
int32_t bottom;
} ARect;
diff --git a/libs/nativewindow/include/android/hardware_buffer.h b/libs/nativewindow/include/android/hardware_buffer.h
index a477bf2..cc67aca 100644
--- a/libs/nativewindow/include/android/hardware_buffer.h
+++ b/libs/nativewindow/include/android/hardware_buffer.h
@@ -41,9 +41,11 @@
AHARDWAREBUFFER_FORMAT_R8G8B8A8_UNORM = 1,
/**
+ * 32 bits per pixel, 8 bits per channel format where alpha values are
+ * ignored (always opaque).
* Corresponding formats:
* Vulkan: VK_FORMAT_R8G8B8A8_UNORM
- * OpenGL ES: GL_RGBA8
+ * OpenGL ES: GL_RGB8
*/
AHARDWAREBUFFER_FORMAT_R8G8B8X8_UNORM = 2,
@@ -124,40 +126,49 @@
AHARDWAREBUFFER_FORMAT_S8_UINT = 0x35,
};
+/**
+ * Buffer usage flags, specifying how the buffer will be accessed.
+ */
enum {
- /* The buffer will never be read by the CPU */
+ /// The buffer will never be read by the CPU.
AHARDWAREBUFFER_USAGE_CPU_READ_NEVER = 0UL,
- /* The buffer will sometimes be read by the CPU */
+ /// The buffer will sometimes be read by the CPU.
AHARDWAREBUFFER_USAGE_CPU_READ_RARELY = 2UL,
- /* The buffer will often be read by the CPU */
+ /// The buffer will often be read by the CPU.
AHARDWAREBUFFER_USAGE_CPU_READ_OFTEN = 3UL,
- /* CPU read value mask */
+ /// CPU read value mask.
AHARDWAREBUFFER_USAGE_CPU_READ_MASK = 0xFUL,
- /* The buffer will never be written by the CPU */
+ /// The buffer will never be written by the CPU.
AHARDWAREBUFFER_USAGE_CPU_WRITE_NEVER = 0UL << 4,
- /* The buffer will sometimes be written to by the CPU */
+ /// The buffer will sometimes be written to by the CPU.
AHARDWAREBUFFER_USAGE_CPU_WRITE_RARELY = 2UL << 4,
- /* The buffer will often be written to by the CPU */
+ /// The buffer will often be written to by the CPU.
AHARDWAREBUFFER_USAGE_CPU_WRITE_OFTEN = 3UL << 4,
- /* CPU write value mask */
+ /// CPU write value mask.
AHARDWAREBUFFER_USAGE_CPU_WRITE_MASK = 0xFUL << 4,
- /* The buffer will be read from by the GPU */
+ /// The buffer will be read from by the GPU as a texture.
AHARDWAREBUFFER_USAGE_GPU_SAMPLED_IMAGE = 1UL << 8,
- /* The buffer will be written to by the GPU */
+ /**
+ * The buffer will be written to by the GPU as a framebuffer attachment.
+ * Note that the name of this flag is somewhat misleading: it does not imply
+ * that the buffer contains a color format. A buffer with depth or stencil
+ * format that will be used as a framebuffer attachment should also have
+ * this flag.
+ */
AHARDWAREBUFFER_USAGE_GPU_COLOR_OUTPUT = 1UL << 9,
- /* The buffer must not be used outside of a protected hardware path */
+ /// The buffer must not be used outside of a protected hardware path.
AHARDWAREBUFFER_USAGE_PROTECTED_CONTENT = 1UL << 14,
- /* The buffer will be read by a hardware video encoder */
+ /// The buffer will be read by a hardware video encoder.
AHARDWAREBUFFER_USAGE_VIDEO_ENCODE = 1UL << 16,
- /* The buffer will be used for sensor direct data */
+ /// The buffer will be used for direct writes from sensors.
AHARDWAREBUFFER_USAGE_SENSOR_DIRECT_DATA = 1UL << 23,
- /* The buffer will be used as a shader storage or uniform buffer object */
+ /// The buffer will be used as a shader storage or uniform buffer object.
AHARDWAREBUFFER_USAGE_GPU_DATA_BUFFER = 1UL << 24,
- /* The buffer will be used as a cube map texture */
+ /// The buffer will be used as a cube map texture.
AHARDWAREBUFFER_USAGE_GPU_CUBE_MAP = 1UL << 25,
- /* The buffer contains a complete mipmap hierarchy */
+ /// The buffer contains a complete mipmap hierarchy.
AHARDWAREBUFFER_USAGE_GPU_MIPMAP_COMPLETE = 1UL << 26,
AHARDWAREBUFFER_USAGE_VENDOR_0 = 1ULL << 28,
@@ -182,15 +193,19 @@
AHARDWAREBUFFER_USAGE_VENDOR_19 = 1ULL << 63,
};
+/**
+ * Buffer description. Used for allocating new buffers and querying parameters
+ * of existing ones.
+ */
typedef struct AHardwareBuffer_Desc {
- uint32_t width; // width in pixels
- uint32_t height; // height in pixels
- uint32_t layers; // number of images
- uint32_t format; // One of AHARDWAREBUFFER_FORMAT_*
- uint64_t usage; // Combination of AHARDWAREBUFFER_USAGE_*
- uint32_t stride; // Stride in pixels, ignored for AHardwareBuffer_allocate()
- uint32_t rfu0; // Initialize to zero, reserved for future use
- uint64_t rfu1; // Initialize to zero, reserved for future use
+ uint32_t width; ///< Width in pixels.
+ uint32_t height; ///< Height in pixels.
+ uint32_t layers; ///< Number of images in an image array.
+ uint32_t format; ///< One of AHARDWAREBUFFER_FORMAT_*
+ uint64_t usage; ///< Combination of AHARDWAREBUFFER_USAGE_*
+ uint32_t stride; ///< Row stride in pixels, ignored for AHardwareBuffer_allocate()
+ uint32_t rfu0; ///< Initialize to zero, reserved for future use.
+ uint64_t rfu1; ///< Initialize to zero, reserved for future use.
} AHardwareBuffer_Desc;
typedef struct AHardwareBuffer AHardwareBuffer;
@@ -199,8 +214,8 @@
* Allocates a buffer that backs an AHardwareBuffer using the passed
* AHardwareBuffer_Desc.
*
- * Returns NO_ERROR on success, or an error number of the allocation fails for
- * any reason.
+ * \return NO_ERROR on success, or an error number of the allocation fails for
+ * any reason. The returned buffer has a reference count of 1.
*/
int AHardwareBuffer_allocate(const AHardwareBuffer_Desc* desc,
AHardwareBuffer** outBuffer);
@@ -223,7 +238,7 @@
void AHardwareBuffer_describe(const AHardwareBuffer* buffer,
AHardwareBuffer_Desc* outDesc);
-/*
+/**
* Lock the AHardwareBuffer for reading or writing, depending on the usage flags
* passed. This call may block if the hardware needs to finish rendering or if
* CPU caches need to be synchronized, or possibly for other implementation-
@@ -231,16 +246,16 @@
* descriptor that will be signaled when the buffer is locked, otherwise the
* caller will block until the buffer is available.
*
- * If rect is not NULL, the caller promises to modify only data in the area
+ * If \a rect is not NULL, the caller promises to modify only data in the area
* specified by rect. If rect is NULL, the caller may modify the contents of the
* entire buffer.
*
* The content of the buffer outside of the specified rect is NOT modified
* by this call.
*
- * The buffer usage may only specify AHARDWAREBUFFER_USAGE_CPU_*. If set, then
- * outVirtualAddress is filled with the address of the buffer in virtual memory,
- * otherwise this function will fail.
+ * The \a usage parameter may only specify AHARDWAREBUFFER_USAGE_CPU_*. If set,
+ * then outVirtualAddress is filled with the address of the buffer in virtual
+ * memory.
*
* THREADING CONSIDERATIONS:
*
@@ -252,38 +267,38 @@
* may return an error or leave the buffer's content into an indeterminate
* state.
*
- * Returns NO_ERROR on success, BAD_VALUE if the buffer is NULL or if the usage
+ * \return NO_ERROR on success, BAD_VALUE if \a buffer is NULL or if the usage
* flags are not a combination of AHARDWAREBUFFER_USAGE_CPU_*, or an error
* number of the lock fails for any reason.
*/
int AHardwareBuffer_lock(AHardwareBuffer* buffer, uint64_t usage,
int32_t fence, const ARect* rect, void** outVirtualAddress);
-/*
+/**
* Unlock the AHardwareBuffer; must be called after all changes to the buffer
* are completed by the caller. If fence is not NULL then it will be set to a
* file descriptor that is signaled when all pending work on the buffer is
* completed. The caller is responsible for closing the fence when it is no
* longer needed.
*
- * Returns NO_ERROR on success, BAD_VALUE if the buffer is NULL, or an error
- * number of the lock fails for any reason.
+ * \return NO_ERROR on success, BAD_VALUE if \a buffer is NULL, or an error
+ * number if the unlock fails for any reason.
*/
int AHardwareBuffer_unlock(AHardwareBuffer* buffer, int32_t* fence);
-/*
+/**
* Send the AHardwareBuffer to an AF_UNIX socket.
*
- * Returns NO_ERROR on success, BAD_VALUE if the buffer is NULL, or an error
- * number of the lock fails for any reason.
+ * \return NO_ERROR on success, BAD_VALUE if \a buffer is NULL, or an error
+ * number if the operation fails for any reason.
*/
int AHardwareBuffer_sendHandleToUnixSocket(const AHardwareBuffer* buffer, int socketFd);
-/*
+/**
* Receive the AHardwareBuffer from an AF_UNIX socket.
*
- * Returns NO_ERROR on success, BAD_VALUE if the buffer is NULL, or an error
- * number of the lock fails for any reason.
+ * \return NO_ERROR on success, BAD_VALUE if \a outBuffer is NULL, or an error
+ * number if the operation fails for any reason.
*/
int AHardwareBuffer_recvHandleFromUnixSocket(int socketFd, AHardwareBuffer** outBuffer);
diff --git a/libs/nativewindow/include/android/native_window.h b/libs/nativewindow/include/android/native_window.h
index f2d6f7a..d5e5e9d 100644
--- a/libs/nativewindow/include/android/native_window.h
+++ b/libs/nativewindow/include/android/native_window.h
@@ -85,23 +85,23 @@
* A pointer can be obtained using {@link ANativeWindow_lock()}.
*/
typedef struct ANativeWindow_Buffer {
- // The number of pixels that are show horizontally.
+ /// The number of pixels that are shown horizontally.
int32_t width;
- // The number of pixels that are shown vertically.
+ /// The number of pixels that are shown vertically.
int32_t height;
- // The number of *pixels* that a line in the buffer takes in
- // memory. This may be >= width.
+ /// The number of *pixels* that a line in the buffer takes in
+ /// memory. This may be >= width.
int32_t stride;
- // The format of the buffer. One of AHARDWAREBUFFER_FORMAT_*
+ /// The format of the buffer. One of AHARDWAREBUFFER_FORMAT_*
int32_t format;
- // The actual bits.
+ /// The actual bits.
void* bits;
- // Do not touch.
+ /// Do not touch.
uint32_t reserved[6];
} ANativeWindow_Buffer;