Donate to e Foundation | Murena handsets with /e/OS | Own a part of Murena! Learn more

Commit dc9c4118 authored by Dan Albert's avatar Dan Albert
Browse files

Expand Choreographer docs. 

This (hopefully) explains all the bits that confused me when I tried
to use these APIs for the first time. The existing docs leaned a lot
on developers already understanding the Java API, and even the Java
API docs didn't explain how to use this portion of the API well.

Bug: None
Test: I am the test
Change-Id: I48490112f92ef754b38daef7a4ebf6c031cc20f8
parent 9ca6b3d5

include/android/choreographer.h

+54 −14
Original line number Diff line number Diff line
@@ -17,8 +17,20 @@ 
/**

 * @addtogroup Choreographer

 *

 * Choreographer coordinates the timing of frame rendering. This is the C version of the

 * android.view.Choreographer object in Java.

 * Choreographer coordinates the timing of frame rendering. This is the C

 * version of the android.view.Choreographer object in Java. If you do not use

 * Choreographer to pace your render loop, you may render too quickly for the

 * display, increasing latency between frame submission and presentation.

 *

 * Input events are guaranteed to be processed before the frame callback is

 * called, and will not be run concurrently. Input and sensor events should not

 * be handled in the Choregrapher callback.

 *

 * The frame callback is also the appropriate place to run any per-frame state

 * update logic. For example, in a game, the frame callback should be

 * responsible for updating things like physics, AI, game state, and rendering

 * the frame. Input and sensors should be handled separately via callbacks

 * registered with AInputQueue and ASensorManager.

 *

 * 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:
@@ -38,6 +50,11 @@ 
 * 4. SurfaceFlinger attempts to follow the chosen frame timeline, by not applying transactions or

 * latching buffers before the desired presentation time.

 *

 * On older devices, AChoreographer_postFrameCallback64 or

 * AChoreographer_postFrameCallback can be used to lesser effect. They cannot be

 * used to precisely plan your render timeline, but will rate limit to avoid

 * overloading the display pipeline and increasing frame latency.

 *

 * @{

 */
@@ -119,8 +136,13 @@ typedef void (*AChoreographer_refreshRateCallback)(int64_t vsyncPeriodNanos, voi 
AChoreographer* AChoreographer_getInstance() __INTRODUCED_IN(24);



/**

 * 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.

 * Post a callback to be run when the application should begin rendering the

 * next frame. The data pointer provided will be passed to the callback function

 * when it's called.

 *

 * The callback will only be run for the next frame, not all subsequent frames,

 * so to render continuously the callback should itself call

 * AChoreographer_postFrameCallback.

 *

 * \bug The callback receives the frame time in nanoseconds as a long. On 32-bit

 * systems, long is 32-bit, so the frame time will roll over roughly every two
@@ -137,9 +159,13 @@ void AChoreographer_postFrameCallback(AChoreographer* choreographer, 
        __INTRODUCED_IN(24) __DEPRECATED_IN(29, "Use AChoreographer_postFrameCallback64 instead");



/**

 * Post a callback to be run on the frame following the specified delay. The

 * data pointer provided will be passed to the callback function when it's

 * called.

 * Post a callback to be run when the application should begin rendering the

 * next frame following the specified delay. The data pointer provided will be

 * passed to the callback function when it's called.

 *

 * The callback will only be run for the next frame after the delay, not all

 * subsequent frames, so to render continuously the callback should itself call

 * AChoreographer_postFrameCallbackDelayed.

 *

 * \bug The callback receives the frame time in nanoseconds as a long. On 32-bit

 * systems, long is 32-bit, so the frame time will roll over roughly every two
@@ -157,8 +183,13 @@ void AChoreographer_postFrameCallbackDelayed(AChoreographer* choreographer, 
        __DEPRECATED_IN(29, "Use AChoreographer_postFrameCallbackDelayed64 instead");



/**

 * 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.

 * Post a callback to be run when the application should begin rendering the

 * next frame. The data pointer provided will be passed to the callback function

 * when it's called.

 *

 * The callback will only be run on the next frame, not all subsequent frames,

 * so to render continuously the callback should itself call

 * AChoreographer_postFrameCallback64.

 *

 * Available since API level 29.

 */
@@ -167,9 +198,13 @@ void AChoreographer_postFrameCallback64(AChoreographer* choreographer, 
        __INTRODUCED_IN(29);



/**

 * Post a callback to be run on the frame following the specified delay.  The

 * data pointer provided will be passed to the callback function when it's

 * called.

 * Post a callback to be run when the application should begin rendering the

 * next frame following the specified delay. The data pointer provided will be

 * passed to the callback function when it's called.

 *

 * The callback will only be run for the next frame after the delay, not all

 * subsequent frames, so to render continuously the callback should itself call

 * AChoreographer_postFrameCallbackDelayed64.

 *

 * Available since API level 29.

 */
@@ -178,8 +213,13 @@ void AChoreographer_postFrameCallbackDelayed64(AChoreographer* choreographer, 
                                               uint32_t delayMillis) __INTRODUCED_IN(29);



/**

 * 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.

 * Posts a callback to be run when the application should begin rendering the

 * next frame. The data pointer provided will be passed to the callback function

 * when it's called.

 *

 * The callback will only be run for the next frame, not all subsequent frames,

 * so to render continuously the callback should itself call

 * AChoreographer_postVsyncCallback.

 *

 * Available since API level 33.

 */