Merge "docs: Clarify the lifetime of AHardwareBuffer_toHardwareBuffer in docs. See generated output in cl/320449087. Bug: 140885254 Test: m ndk" into rvc-dev-plus-aosp am: efb33042fd am: ee5f2c2a18 am: 7c46baf3e0
Original change: https://googleplex-android-review.googlesource.com/c/platform/frameworks/native/+/12122047
Change-Id: I5cd90e6b362e9dfe80d13c74fd30fb954b9cd6a2
diff --git a/include/android/hardware_buffer_jni.h b/include/android/hardware_buffer_jni.h
index 293e5ac..ae208a6 100644
--- a/include/android/hardware_buffer_jni.h
+++ b/include/android/hardware_buffer_jni.h
@@ -39,9 +39,9 @@
* Return the AHardwareBuffer wrapped by a Java HardwareBuffer object.
*
* This method does not acquire any additional reference to the AHardwareBuffer
- * that is returned. To keep the AHardwareBuffer live after the Java
- * HardwareBuffer object got garbage collected, be sure to use AHardwareBuffer_acquire()
- * to acquire an additional reference.
+ * that is returned. To keep the AHardwareBuffer alive after the Java
+ * HardwareBuffer object is closed, explicitly or by the garbage collector, be
+ * sure to use AHardwareBuffer_acquire() to acquire an additional reference.
*
* Available since API level 26.
*/
@@ -50,7 +50,18 @@
/**
* Return a new Java HardwareBuffer object that wraps the passed native
- * AHardwareBuffer object.
+ * AHardwareBuffer object. The Java HardwareBuffer will acquire a reference to
+ * the internal buffer and manage its lifetime. For example:
+ *
+ * <pre><code>
+ * AHardwareBuffer* buffer;
+ * AHardwareBuffer_allocate(..., &buffer); // `buffer` has reference count 1
+ * jobject java_result = AHardwareBuffer_toHardwareBuffer(buffer); // `buffer` has reference count 2.
+ * AHardwareBuffer_release(buffer); // `buffer` has reference count 1
+ * return result; // The underlying buffer is kept alive by `java_result` and
+ * // will be set to 0 when it is closed on the Java side with
+ * // HardwareBuffer::close().
+ * </code></pre>
*
* Available since API level 26.
*/