Merge "gralloc: clarify lock_ycbcr in light of multimedia codec usage" into lmp-mr1-devandroid-5.1.1_r5android-5.1.1_r28android-5.1.1_r22android-5.1.1_r17android-5.1.1_r12lollipop-mr1-wfc-releaselollipop-mr1-dev

1 files changed, 11 insertions, 2 deletions

diff --git a/include/hardware/gralloc.h b/include/hardware/gralloc.h
index 91e2f697..7d00114a 100644
--- a/include/hardware/gralloc.h
+++ b/include/hardware/gralloc.h
@@ -237,8 +237,17 @@ typedef struct gralloc_module_t {
      * difference that it fills a struct ycbcr with a description of the buffer
      * layout, and zeroes out the reserved fields.
      *
-     * This will only work on buffers with HAL_PIXEL_FORMAT_YCbCr_*_888, and
-     * will return -EINVAL on any other buffer formats.
+     * If the buffer format is not compatible with a flexible YUV format (e.g.
+     * the buffer layout cannot be represented with the ycbcr struct), it
+     * will return -EINVAL.
+     *
+     * This method must work on buffers with HAL_PIXEL_FORMAT_YCbCr_*_888
+     * if supported by the device, as well as with any other format that is
+     * requested by the multimedia codecs when they are configured with a
+     * flexible-YUV-compatible color-format with android native buffers.
+     *
+     * Note that this method may also be called on buffers of other formats,
+     * including non-YUV formats.
      *
      * Added in GRALLOC_MODULE_API_VERSION_0_2.
      */