Improve ASurfaceTransaction_setFrameTimeline docs.
Also use a new typedef AVsyncId shared in AChoreographer and
ASurfaceControl.
Test: atest ASurfaceControlTest; atest ChoreographerNativeTest
Bug: 214063411
Change-Id: If24f144404038064de2ba72cca44572aca507e44
diff --git a/include/android/surface_control.h b/include/android/surface_control.h
index 3a13104..9a36ecb 100644
--- a/include/android/surface_control.h
+++ b/include/android/surface_control.h
@@ -28,6 +28,7 @@
#include <sys/cdefs.h>
+#include <android/choreographer.h>
#include <android/data_space.h>
#include <android/hardware_buffer.h>
#include <android/hdr_metadata.h>
@@ -596,13 +597,23 @@
__INTRODUCED_IN(31);
/**
- * Sets the frame timeline to use.
+ * Sets the frame timeline to use in Surface Flinger.
+ *
+ * A frame timeline should be chosen based on what frame deadline the application
+ * can meet when rendering the frame and the application's desired present time.
+ * By setting a frame timeline, Surface Flinger tries to present the frame at the corresponding
+ * expected present time.
+ *
+ * To receive frame timelines, a callback must be posted to Choreographer using
+ * AChoreographer_postExtendedFrameCallback(). The \a vsnycId can then be extracted from the
+ * callback payload using AChoreographerFrameCallbackData_getFrameTimelineVsyncId().
*
* \param vsyncId The vsync ID received from AChoreographer, setting the frame's present target to
- * the corresponding expected present time and deadline from the frame to be rendered.
+ * the corresponding expected present time and deadline from the frame to be rendered. A stale or
+ * invalid value will be ignored.
*/
void ASurfaceTransaction_setFrameTimeline(ASurfaceTransaction* transaction,
- int64_t vsyncId) __INTRODUCED_IN(33);
+ AVsyncId vsyncId) __INTRODUCED_IN(33);
__END_DECLS