Clarify new Choreographer Android 13 NDK docs. am: a4aba5d7dd (1d1dce8a) · Commits · e / os / android_frameworks_native

include/android/choreographer.h

+52 −10

Original line number	Diff line number	Diff line
		@@ -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);

include/android/surface_control.h

+9 −9

Original line number	Diff line number	Diff line
		@@ -599,18 +599,18 @@ void ASurfaceTransaction_setEnableBackPressure(ASurfaceTransaction* transaction,
		/**
		* 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.
		* 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 present time.
		* 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);