Merge "Add more javadocs to SyncFence" into tm-dev

core/java/android/hardware/SyncFence.java

@@ -17,6 +17,8 @@
 package android.hardware;
 
 import android.annotation.NonNull;
+import android.media.Image;
+import android.media.ImageWriter;
 import android.opengl.EGLDisplay;
 import android.opengl.EGLSync;
 import android.os.Parcel;
@@ -30,14 +32,29 @@ import java.io.IOException;
 import java.time.Duration;
 
 /**
- * A SyncFence represents a synchronization primitive which signals when hardware buffers have
+ * A SyncFence represents a synchronization primitive which signals when hardware units have
- * completed work on a particular resource.
+ * completed work on a particular resource. They initially start in an unsignaled state and make
+ * a one-time transition to either a signaled or error state. SyncFences are created by various
+ * device APIs in response to submitting tasks to the device. They cannot be created nor signaled
+ * by userspace. As a result, this means that a SyncFence will make always make forward progress.
+ *
+ * <p>SyncFence's generally come in one of two varieties. "Presentation fences" refer to
+ *  a SyncFence when the writing to a buffer has finished. "Release fences" then refer
+ *  to when the reading from a buffer has finished.</p>
  *
  * <p>For example, a GPU rendering to a framebuffer may generate a synchronization fence,
- * e.g., a VkFence, which signals when rendering has completed.
+ * e.g., an EGLSync or VkFence, which signals when rendering has completed. Once the fence signals,
+ * then the backing storage for the framebuffer may be safely read from, such as for display or
+ * for media encoding. This would be referred to as a "presentation fence."</p>
  *
- * Once the fence signals, then the backing storage for the framebuffer may be safely read from,
+ * <p>Similarly when using an {@link android.media.ImageWriter} it is possible that an
- * such as for display or for media encoding.</p>
+ * {@link android.media.Image} returned by {@link ImageWriter#dequeueInputImage()} may already
+ * have a {@link Image#getFence() fence} set on it. This would be what is referred to as either
+ * a "release fence" or an "acqurie fence" and indicates the fence that the writer must wait
+ * on before writing to the underlying buffer. In the case of ImageWriter this is done
+ * automatically when eg {@link Image#getPlanes()} is called, however when using
+ * {@link Image#getHardwareBuffer()} it is the caller's responsibility to ensure the
+ * release fence has signaled before writing to the buffer.</p>
  *
  * @see android.opengl.EGLExt#eglDupNativeFenceFDANDROID(EGLDisplay, EGLSync)
  * @see android.media.Image#getFence()