diff options
| author | Dan Albert <danalbert@google.com> | 2024-05-02 20:36:06 +0000 |
|---|---|---|
| committer | Dan Albert <danalbert@google.com> | 2024-05-02 20:50:29 +0000 |
| commit | 9ca6b3d5c80155b15530845b945263c02bf84ca4 (patch) | |
| tree | 096699a43cbce6bbe033df1251b01d3e7b5dba1c /include | |
| parent | b06c7fba2d2748b9b11763bc3ba2d1ca86941e64 (diff) | |
| download | native-9ca6b3d5c80155b15530845b945263c02bf84ca4.tar.gz | |
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
Diffstat (limited to 'include')
| -rw-r--r-- | include/android/choreographer.h | 27 |
1 files changed, 25 insertions, 2 deletions
diff --git a/include/android/choreographer.h b/include/android/choreographer.h index c4d1ca65be..b0248bd0ef 100644 --- a/include/android/choreographer.h +++ b/include/android/choreographer.h @@ -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, |