Merge "frameworks/av: Documentation fixes for AImage and AImageReader." into pi-dev
diff --git a/media/ndk/include/media/NdkImage.h b/media/ndk/include/media/NdkImage.h
index 99cf5d5..19df760 100644
--- a/media/ndk/include/media/NdkImage.h
+++ b/media/ndk/include/media/NdkImage.h
@@ -72,14 +72,15 @@
AIMAGE_FORMAT_RGBA_8888 = 0x1,
/**
- * 32 bits RGBX format, 8 bits for each of the four channels.
+ * 32 bits RGBX format, 8 bits for each of the four channels. The values
+ * of the alpha channel bits are ignored (image is assumed to be opaque).
*
* <p>
* Corresponding formats:
* <ul>
* <li>AHardwareBuffer: AHARDWAREBUFFER_FORMAT_R8G8B8X8_UNORM</li>
* <li>Vulkan: VK_FORMAT_R8G8B8A8_UNORM</li>
- * <li>OpenGL ES: GL_RGBA8</li>
+ * <li>OpenGL ES: GL_RGB8</li>
* </ul>
* </p>
*
@@ -717,7 +718,7 @@
#if __ANDROID_API__ >= 26
-/*
+/**
* Return the image back the the system and delete the AImage object from memory asynchronously.
*
* <p>Similar to {@link AImage_delete}, do NOT use the image pointer after this method returns.
@@ -746,8 +747,9 @@
* AHardwareBuffer_acquire} to acquire an extra reference, and call {@link AHardwareBuffer_release}
* once it has finished using it in order to properly deallocate the underlying memory managed by
* {@link AHardwareBuffer}. If the caller has acquired extra reference on an {@link AHardwareBuffer}
- * returned from this function, it must also listen to {@link onBufferFreed} callback to be
- * notified when the buffer is no longer used by {@link AImageReader}.</p>
+ * returned from this function, it must also register a listener using the function
+ * {@link AImageReader_setBufferRemovedListener} to be notified when the buffer is no longer used
+ * by {@link AImageReader}.</p>
*
* @param image the {@link AImage} of interest.
* @param outBuffer The memory area pointed to by buffer will contain the acquired AHardwareBuffer
diff --git a/media/ndk/include/media/NdkImageReader.h b/media/ndk/include/media/NdkImageReader.h
index e3b99d0..571410b 100644
--- a/media/ndk/include/media/NdkImageReader.h
+++ b/media/ndk/include/media/NdkImageReader.h
@@ -256,7 +256,7 @@
/**
- * The definition of {@link AImageReader} new image available callback.
+ * Signature of the callback which is called when a new image is available from {@link AImageReader}.
*
* @param context The optional application context provided by user in
* {@link AImageReader_setImageListener}.
@@ -265,11 +265,11 @@
typedef void (*AImageReader_ImageCallback)(void* context, AImageReader* reader);
typedef struct AImageReader_ImageListener {
- /// optional application context.
+ /// Optional application context passed as the first parameter of the callback.
void* context;
/**
- * This callback is called when there is a new image available for in the image reader's queue.
+ * This callback is called when there is a new image available in the image reader's queue.
*
* <p>The callback happens on one dedicated thread per {@link AImageReader} instance. It is okay
* to use AImageReader_* and AImage_* methods within the callback. Note that it is possible that
@@ -285,11 +285,11 @@
/**
* Set the onImageAvailable listener of this image reader.
*
- * <p>Note that calling this method will replace previously registered listeners.</p>
+ * Calling this method will replace previously registered listeners.
*
* @param reader The image reader of interest.
- * @param listener the {@link AImageReader_ImageListener} to be registered. Set this to NULL if
- * application no longer needs to listen to new images.
+ * @param listener The {@link AImageReader_ImageListener} to be registered. Set this to NULL if
+ * the application no longer needs to listen to new images.
*
* @return <ul>
* <li>{@link AMEDIA_OK} if the method call succeeds.</li>
@@ -406,7 +406,7 @@
media_status_t AImageReader_acquireLatestImageAsync(
AImageReader* reader, /*out*/AImage** image, /*out*/int* acquireFenceFd);
/**
- * The definition of {@link AImageReader} buffer removed callback.
+ * Signature of the callback which is called when {@link AImageReader} is about to remove a buffer.
*
* @param context The optional application context provided by user in
* {@link AImageReader_setBufferRemovedListener}.
@@ -418,7 +418,7 @@
AHardwareBuffer* buffer);
typedef struct AImageReader_BufferRemovedListener {
- /// optional application context.
+ /// Optional application context passed as the first parameter of the callback.
void* context;
/**