From a4aba5d7dd1467f9a4a80c7836e50b6465b735c4 Mon Sep 17 00:00:00 2001 From: Rachel Lee Date: Tue, 23 Aug 2022 14:37:59 -0700 Subject: Clarify new Choreographer Android 13 NDK docs. Bug: 227383300 Test: doxygen local generated docs Change-Id: Iee46c5b4ae053fb9a72511329d6e974afa59e478 (cherry picked from commit e81bf2616ea406d9ee9deb038c6978cdb84d6d35) --- include/android/choreographer.h | 62 ++++++++++++++++++++++++++++++++------- include/android/surface_control.h | 18 ++++++------ 2 files changed, 61 insertions(+), 19 deletions(-) diff --git a/include/android/choreographer.h b/include/android/choreographer.h index 63aa7ff6c0..cd8e63dec2 100644 --- a/include/android/choreographer.h +++ b/include/android/choreographer.h @@ -16,6 +16,28 @@ /** * @addtogroup Choreographer + * + * Choreographer coordinates the timing of frame rendering. This is the C version of the + * android.view.Choreographer object in Java. + * + * As of API level 33, apps can follow proper frame pacing and even choose a future frame to render. + * The API is used as follows: + * 1. The app posts an {@link AChoreographer_vsyncCallback} to Choreographer to run on the next + * frame. + * 2. The callback is called when it is the time to start the frame with an {@link + * AChoreographerFrameCallbackData} payload: information about multiple possible frame + * timelines. + * 3. Apps can choose a frame timeline from the {@link + * AChoreographerFrameCallbackData} payload, depending on the frame deadline they can meet when + * rendering the frame and their desired presentation time, and subsequently + * {@link ASurfaceTransaction_setFrameTimeline notify SurfaceFlinger} + * of the choice. Alternatively, for apps that do not choose a frame timeline, their frame would be + * presented at the earliest possible timeline. + * - The preferred frame timeline is the default frame + * timeline that the platform scheduled for the app, based on device configuration. + * 4. SurfaceFlinger attempts to follow the chosen frame timeline, by not applying transactions or + * latching buffers before the desired presentation time. + * * @{ */ @@ -47,7 +69,8 @@ typedef int64_t AVsyncId; struct AChoreographerFrameCallbackData; /** - * Opaque type that provides access to an AChoreographerFrameCallbackData object. + * Opaque type that provides access to an AChoreographerFrameCallbackData object, which contains + * various methods to extract frame information. */ typedef struct AChoreographerFrameCallbackData AChoreographerFrameCallbackData; @@ -73,8 +96,9 @@ typedef void (*AChoreographer_frameCallback64)(int64_t frameTimeNanos, void* dat /** * Prototype of the function that is called when a new frame is being rendered. - * It's passed the frame data that should not outlive the callback, as well as the data pointer - * provided by the application that registered a callback. + * It is called with \c callbackData describing multiple frame timelines, as well as the \c data + * pointer provided by the application that registered a callback. The \c callbackData does not + * outlive the callback. */ typedef void (*AChoreographer_vsyncCallback)( const AChoreographerFrameCallbackData* callbackData, void* data); @@ -110,7 +134,7 @@ void AChoreographer_postFrameCallbackDelayed(AChoreographer* choreographer, __DEPRECATED_IN(29); /** - * Power a callback to be run on the next frame. The data pointer provided will + * Post a callback to be run on the next frame. The data pointer provided will * be passed to the callback function when it's called. * * Available since API level 29. @@ -131,8 +155,10 @@ void AChoreographer_postFrameCallbackDelayed64(AChoreographer* choreographer, uint32_t delayMillis) __INTRODUCED_IN(29); /** - * Posts a callback to run on the next frame. The data pointer provided will + * Posts a callback to be run on the next frame. The data pointer provided will * be passed to the callback function when it's called. + * + * Available since API level 33. */ void AChoreographer_postVsyncCallback(AChoreographer* choreographer, AChoreographer_vsyncCallback callback, void* data) @@ -189,7 +215,10 @@ void AChoreographer_unregisterRefreshRateCallback(AChoreographer* choreographer, __INTRODUCED_IN(30); /** - * The time in nanoseconds when the frame started being rendered. + * The time in nanoseconds at which the frame started being rendered. + * + * Note that this time should \b not be used to advance animation clocks. + * Instead, see AChoreographerFrameCallbackData_getFrameTimelineExpectedPresentationTimeNanos(). */ int64_t AChoreographerFrameCallbackData_getFrameTimeNanos( const AChoreographerFrameCallbackData* data) __INTRODUCED_IN(33); @@ -201,25 +230,38 @@ size_t AChoreographerFrameCallbackData_getFrameTimelinesLength( const AChoreographerFrameCallbackData* data) __INTRODUCED_IN(33); /** - * Get index of the platform-preferred FrameTimeline. + * Gets the index of the platform-preferred frame timeline. + * The preferred frame timeline is the default + * by which the platform scheduled the app, based on the device configuration. */ size_t AChoreographerFrameCallbackData_getPreferredFrameTimelineIndex( const AChoreographerFrameCallbackData* data) __INTRODUCED_IN(33); /** - * The vsync ID token used to map Choreographer data. + * Gets the token used by the platform to identify the frame timeline at the given \c index. + * + * \param index index of a frame timeline, in \f( [0, FrameTimelinesLength) \f). See + * AChoreographerFrameCallbackData_getFrameTimelinesLength() */ AVsyncId AChoreographerFrameCallbackData_getFrameTimelineVsyncId( const AChoreographerFrameCallbackData* data, size_t index) __INTRODUCED_IN(33); /** - * The time in nanoseconds which the frame at given index is expected to be presented. + * Gets the time in nanoseconds at which the frame described at the given \c index is expected to + * be presented. This time should be used to advance any animation clocks. + * + * \param index index of a frame timeline, in \f( [0, FrameTimelinesLength) \f). See + * AChoreographerFrameCallbackData_getFrameTimelinesLength() */ int64_t AChoreographerFrameCallbackData_getFrameTimelineExpectedPresentationTimeNanos( const AChoreographerFrameCallbackData* data, size_t index) __INTRODUCED_IN(33); /** - * The time in nanoseconds which the frame at given index needs to be ready by. + * Gets the time in nanoseconds at which the frame described at the given \c index needs to be + * ready by in order to be presented on time. + * + * \param index index of a frame timeline, in \f( [0, FrameTimelinesLength) \f). See + * AChoreographerFrameCallbackData_getFrameTimelinesLength() */ int64_t AChoreographerFrameCallbackData_getFrameTimelineDeadlineNanos( const AChoreographerFrameCallbackData* data, size_t index) __INTRODUCED_IN(33); diff --git a/include/android/surface_control.h b/include/android/surface_control.h index 9a36ecb537..6223ef7f82 100644 --- a/include/android/surface_control.h +++ b/include/android/surface_control.h @@ -597,20 +597,20 @@ void ASurfaceTransaction_setEnableBackPressure(ASurfaceTransaction* transaction, __INTRODUCED_IN(31); /** - * Sets the frame timeline to use in Surface Flinger. + * Sets the frame timeline to use in SurfaceFlinger. * - * 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. + * A frame timeline should be chosen based on the frame deadline the application + * can meet when rendering the frame and the application's desired presentation time. + * By setting a frame timeline, SurfaceFlinger tries to present the frame at the corresponding + * expected presentation time. * * To receive frame timelines, a callback must be posted to Choreographer using - * AChoreographer_postExtendedFrameCallback(). The \a vsnycId can then be extracted from the + * AChoreographer_postVsyncCallback(). The \c vsyncId 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. A stale or - * invalid value will be ignored. + * \param vsyncId The vsync ID received from AChoreographer, setting the frame's presentation target + * to the corresponding expected presentation time and deadline from the frame to be rendered. A + * stale or invalid value will be ignored. */ void ASurfaceTransaction_setFrameTimeline(ASurfaceTransaction* transaction, AVsyncId vsyncId) __INTRODUCED_IN(33); -- cgit v1.2.3