From 885fc0e45a743ed6e6391df1b185e708e9b6b625 Mon Sep 17 00:00:00 2001
From: John Reck <jreck@google.com>
Date: Tue, 15 Feb 2022 18:19:07 -0500
Subject: Add more javadocs to SyncFence

Test: make offline-sdk-docs
Fixes: 218860229
Change-Id: Ia8adacf02358a43126df4c996842d5f67071ad71
---
 core/java/android/hardware/SyncFence.java | 27 ++++++++++++++++++++++-----
 1 file changed, 22 insertions(+), 5 deletions(-)

diff --git a/core/java/android/hardware/SyncFence.java b/core/java/android/hardware/SyncFence.java
index 99791ce3d8ec..cd4bf78f0879 100644
--- a/core/java/android/hardware/SyncFence.java
+++ b/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
- * completed work on a particular resource.
+ * A SyncFence represents a synchronization primitive which signals when hardware units have
+ * 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,
- * such as for display or for media encoding.</p>
+ * <p>Similarly when using an {@link android.media.ImageWriter} it is possible that an
+ * {@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()
-- 
cgit v1.2.3-59-g8ed1b