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

Commit 9ca6b3d5 authored by Dan Albert's avatar Dan Albert
Browse files

Restore docs for deprecated Choreographer APIs. 

They're deprecated, but still needed by most users, as the replacement
is not available until API 29. Restore the docs and explain the bugs.

Bug: None
Test: treehugger
Change-Id: I4227ce3f0ee57a73a13e394cd48373accf4a58a3
parent b06c7fba

include/android/choreographer.h

+25 −2
Original line number Diff line number Diff line
@@ -119,14 +119,37 @@ typedef void (*AChoreographer_refreshRateCallback)(int64_t vsyncPeriodNanos, voi 
AChoreographer* AChoreographer_getInstance() __INTRODUCED_IN(24);



/**

 * Deprecated: Use AChoreographer_postFrameCallback64 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.

 *

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

 * seconds. If your minSdkVersion is 29 or higher, switch to

 * AChoreographer_postFrameCallback64, which uses a 64-bit frame time for all

 * platforms. For older OS versions, you must combine the argument with the

 * upper bits of clock_gettime(CLOCK_MONOTONIC, ...) on 32-bit systems.

 *

 * \deprecated Use AChoreographer_postFrameCallback64, which does not have the

 * bug described above.

 */

void AChoreographer_postFrameCallback(AChoreographer* choreographer,

                                      AChoreographer_frameCallback callback, void* data)

        __INTRODUCED_IN(24) __DEPRECATED_IN(29, "Use AChoreographer_postFrameCallback64 instead");



/**

 * Deprecated: Use AChoreographer_postFrameCallbackDelayed64 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.

 *

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

 * seconds. If your minSdkVersion is 29 or higher, switch to

 * AChoreographer_postFrameCallbackDelayed64, which uses a 64-bit frame time for

 * all platforms. For older OS versions, you must combine the argument with the

 * upper bits of clock_gettime(CLOCK_MONOTONIC, ...) on 32-bit systems.

 *

 * \deprecated Use AChoreographer_postFrameCallbackDelayed64, which does not

 * have the bug described above.

 */

void AChoreographer_postFrameCallbackDelayed(AChoreographer* choreographer,

                                             AChoreographer_frameCallback callback, void* data,