Android/frameworks_base
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Add more javadocs to SyncFence

Browse Source 
Test: make offline-sdk-docs
Fixes: 218860229
Change-Id: Ia8adacf02358a43126df4c996842d5f67071ad71
This commit is contained in:
John Reck
2022-02-15 18:19:07 -05:00
parent 1afc1f40e2
commit 885fc0e45a
1 changed files with 22 additions and 5 deletions
Download Patch File Download Diff File Expand all files Collapse all files

27
core/java/android/hardware/SyncFence.java
View File

@@ -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()