diff options
| -rw-r--r-- | core/java/android/hardware/SyncFence.java | 27 |
1 files 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() |