PageRenderTime 60ms CodeModel.GetById 23ms RepoModel.GetById 1ms app.codeStats 0ms

/core/java/android/view/Choreographer.java

https://github.com/azmi-multazam/platform_frameworks_base
Java | 834 lines | 455 code | 82 blank | 297 comment | 87 complexity | 91455bd3f5fee3dddc58461bf54458e0 MD5 | raw file
  1. /*
  2. * Copyright (C) 2011 The Android Open Source Project
  3. *
  4. * Licensed under the Apache License, Version 2.0 (the "License");
  5. * you may not use this file except in compliance with the License.
  6. * You may obtain a copy of the License at
  7. *
  8. * http://www.apache.org/licenses/LICENSE-2.0
  9. *
  10. * Unless required by applicable law or agreed to in writing, software
  11. * distributed under the License is distributed on an "AS IS" BASIS,
  12. * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  13. * See the License for the specific language governing permissions and
  14. * limitations under the License.
  15. */
  16. package android.view;
  17. import android.hardware.display.DisplayManagerGlobal;
  18. import android.os.Handler;
  19. import android.os.Looper;
  20. import android.os.Message;
  21. import android.os.SystemClock;
  22. import android.os.SystemProperties;
  23. import android.util.Log;
  24. import android.util.TimeUtils;
  25. import java.io.PrintWriter;
  26. /**
  27. * Coordinates the timing of animations, input and drawing.
  28. * <p>
  29. * The choreographer receives timing pulses (such as vertical synchronization)
  30. * from the display subsystem then schedules work to occur as part of rendering
  31. * the next display frame.
  32. * </p><p>
  33. * Applications typically interact with the choreographer indirectly using
  34. * higher level abstractions in the animation framework or the view hierarchy.
  35. * Here are some examples of things you can do using the higher-level APIs.
  36. * </p>
  37. * <ul>
  38. * <li>To post an animation to be processed on a regular time basis synchronized with
  39. * display frame rendering, use {@link android.animation.ValueAnimator#start}.</li>
  40. * <li>To post a {@link Runnable} to be invoked once at the beginning of the next display
  41. * frame, use {@link View#postOnAnimation}.</li>
  42. * <li>To post a {@link Runnable} to be invoked once at the beginning of the next display
  43. * frame after a delay, use {@link View#postOnAnimationDelayed}.</li>
  44. * <li>To post a call to {@link View#invalidate()} to occur once at the beginning of the
  45. * next display frame, use {@link View#postInvalidateOnAnimation()} or
  46. * {@link View#postInvalidateOnAnimation(int, int, int, int)}.</li>
  47. * <li>To ensure that the contents of a {@link View} scroll smoothly and are drawn in
  48. * sync with display frame rendering, do nothing. This already happens automatically.
  49. * {@link View#onDraw} will be called at the appropriate time.</li>
  50. * </ul>
  51. * <p>
  52. * However, there are a few cases where you might want to use the functions of the
  53. * choreographer directly in your application. Here are some examples.
  54. * </p>
  55. * <ul>
  56. * <li>If your application does its rendering in a different thread, possibly using GL,
  57. * or does not use the animation framework or view hierarchy at all
  58. * and you want to ensure that it is appropriately synchronized with the display, then use
  59. * {@link Choreographer#postFrameCallback}.</li>
  60. * <li>... and that's about it.</li>
  61. * </ul>
  62. * <p>
  63. * Each {@link Looper} thread has its own choreographer. Other threads can
  64. * post callbacks to run on the choreographer but they will run on the {@link Looper}
  65. * to which the choreographer belongs.
  66. * </p>
  67. */
  68. public final class Choreographer {
  69. private static final String TAG = "Choreographer";
  70. private static final boolean DEBUG = false;
  71. // The default amount of time in ms between animation frames.
  72. // When vsync is not enabled, we want to have some idea of how long we should
  73. // wait before posting the next animation message. It is important that the
  74. // default value be less than the true inter-frame delay on all devices to avoid
  75. // situations where we might skip frames by waiting too long (we must compensate
  76. // for jitter and hardware variations). Regardless of this value, the animation
  77. // and display loop is ultimately rate-limited by how fast new graphics buffers can
  78. // be dequeued.
  79. private static final long DEFAULT_FRAME_DELAY = 10;
  80. // The number of milliseconds between animation frames.
  81. private static volatile long sFrameDelay = DEFAULT_FRAME_DELAY;
  82. // Thread local storage for the choreographer.
  83. private static final ThreadLocal<Choreographer> sThreadInstance =
  84. new ThreadLocal<Choreographer>() {
  85. @Override
  86. protected Choreographer initialValue() {
  87. Looper looper = Looper.myLooper();
  88. if (looper == null) {
  89. throw new IllegalStateException("The current thread must have a looper!");
  90. }
  91. return new Choreographer(looper);
  92. }
  93. };
  94. // Enable/disable vsync for animations and drawing.
  95. private static final boolean USE_VSYNC = SystemProperties.getBoolean(
  96. "debug.choreographer.vsync", true);
  97. // Enable/disable using the frame time instead of returning now.
  98. private static final boolean USE_FRAME_TIME = SystemProperties.getBoolean(
  99. "debug.choreographer.frametime", true);
  100. // Set a limit to warn about skipped frames.
  101. // Skipped frames imply jank.
  102. private static final int SKIPPED_FRAME_WARNING_LIMIT = SystemProperties.getInt(
  103. "debug.choreographer.skipwarning", 30);
  104. private static final long NANOS_PER_MS = 1000000;
  105. private static final int MSG_DO_FRAME = 0;
  106. private static final int MSG_DO_SCHEDULE_VSYNC = 1;
  107. private static final int MSG_DO_SCHEDULE_CALLBACK = 2;
  108. // All frame callbacks posted by applications have this token.
  109. private static final Object FRAME_CALLBACK_TOKEN = new Object() {
  110. public String toString() { return "FRAME_CALLBACK_TOKEN"; }
  111. };
  112. private final Object mLock = new Object();
  113. private final Looper mLooper;
  114. private final FrameHandler mHandler;
  115. // The display event receiver can only be accessed by the looper thread to which
  116. // it is attached. We take care to ensure that we post message to the looper
  117. // if appropriate when interacting with the display event receiver.
  118. private final FrameDisplayEventReceiver mDisplayEventReceiver;
  119. private CallbackRecord mCallbackPool;
  120. private final CallbackQueue[] mCallbackQueues;
  121. private boolean mFrameScheduled;
  122. private boolean mCallbacksRunning;
  123. private long mLastFrameTimeNanos;
  124. private long mFrameIntervalNanos;
  125. /**
  126. * Callback type: Input callback. Runs first.
  127. * @hide
  128. */
  129. public static final int CALLBACK_INPUT = 0;
  130. /**
  131. * Callback type: Animation callback. Runs before traversals.
  132. * @hide
  133. */
  134. public static final int CALLBACK_ANIMATION = 1;
  135. /**
  136. * Callback type: Traversal callback. Handles layout and draw. Runs last
  137. * after all other asynchronous messages have been handled.
  138. * @hide
  139. */
  140. public static final int CALLBACK_TRAVERSAL = 2;
  141. private static final int CALLBACK_LAST = CALLBACK_TRAVERSAL;
  142. private Choreographer(Looper looper) {
  143. mLooper = looper;
  144. mHandler = new FrameHandler(looper);
  145. mDisplayEventReceiver = USE_VSYNC ? new FrameDisplayEventReceiver(looper) : null;
  146. mLastFrameTimeNanos = Long.MIN_VALUE;
  147. mFrameIntervalNanos = (long)(1000000000 / getRefreshRate());
  148. mCallbackQueues = new CallbackQueue[CALLBACK_LAST + 1];
  149. for (int i = 0; i <= CALLBACK_LAST; i++) {
  150. mCallbackQueues[i] = new CallbackQueue();
  151. }
  152. }
  153. private static float getRefreshRate() {
  154. DisplayInfo di = DisplayManagerGlobal.getInstance().getDisplayInfo(
  155. Display.DEFAULT_DISPLAY);
  156. return di.refreshRate;
  157. }
  158. /**
  159. * Gets the choreographer for the calling thread. Must be called from
  160. * a thread that already has a {@link android.os.Looper} associated with it.
  161. *
  162. * @return The choreographer for this thread.
  163. * @throws IllegalStateException if the thread does not have a looper.
  164. */
  165. public static Choreographer getInstance() {
  166. return sThreadInstance.get();
  167. }
  168. /**
  169. * The amount of time, in milliseconds, between each frame of the animation.
  170. * <p>
  171. * This is a requested time that the animation will attempt to honor, but the actual delay
  172. * between frames may be different, depending on system load and capabilities. This is a static
  173. * function because the same delay will be applied to all animations, since they are all
  174. * run off of a single timing loop.
  175. * </p><p>
  176. * The frame delay may be ignored when the animation system uses an external timing
  177. * source, such as the display refresh rate (vsync), to govern animations.
  178. * </p>
  179. *
  180. * @return the requested time between frames, in milliseconds
  181. * @hide
  182. */
  183. public static long getFrameDelay() {
  184. return sFrameDelay;
  185. }
  186. /**
  187. * The amount of time, in milliseconds, between each frame of the animation.
  188. * <p>
  189. * This is a requested time that the animation will attempt to honor, but the actual delay
  190. * between frames may be different, depending on system load and capabilities. This is a static
  191. * function because the same delay will be applied to all animations, since they are all
  192. * run off of a single timing loop.
  193. * </p><p>
  194. * The frame delay may be ignored when the animation system uses an external timing
  195. * source, such as the display refresh rate (vsync), to govern animations.
  196. * </p>
  197. *
  198. * @param frameDelay the requested time between frames, in milliseconds
  199. * @hide
  200. */
  201. public static void setFrameDelay(long frameDelay) {
  202. sFrameDelay = frameDelay;
  203. }
  204. /**
  205. * Subtracts typical frame delay time from a delay interval in milliseconds.
  206. * <p>
  207. * This method can be used to compensate for animation delay times that have baked
  208. * in assumptions about the frame delay. For example, it's quite common for code to
  209. * assume a 60Hz frame time and bake in a 16ms delay. When we call
  210. * {@link #postAnimationCallbackDelayed} we want to know how long to wait before
  211. * posting the animation callback but let the animation timer take care of the remaining
  212. * frame delay time.
  213. * </p><p>
  214. * This method is somewhat conservative about how much of the frame delay it
  215. * subtracts. It uses the same value returned by {@link #getFrameDelay} which by
  216. * default is 10ms even though many parts of the system assume 16ms. Consequently,
  217. * we might still wait 6ms before posting an animation callback that we want to run
  218. * on the next frame, but this is much better than waiting a whole 16ms and likely
  219. * missing the deadline.
  220. * </p>
  221. *
  222. * @param delayMillis The original delay time including an assumed frame delay.
  223. * @return The adjusted delay time with the assumed frame delay subtracted out.
  224. * @hide
  225. */
  226. public static long subtractFrameDelay(long delayMillis) {
  227. final long frameDelay = sFrameDelay;
  228. return delayMillis <= frameDelay ? 0 : delayMillis - frameDelay;
  229. }
  230. void dump(String prefix, PrintWriter writer) {
  231. String innerPrefix = prefix + " ";
  232. writer.print(prefix); writer.println("Choreographer:");
  233. writer.print(innerPrefix); writer.print("mFrameScheduled=");
  234. writer.println(mFrameScheduled);
  235. writer.print(innerPrefix); writer.print("mLastFrameTime=");
  236. writer.println(TimeUtils.formatUptime(mLastFrameTimeNanos / 1000000));
  237. }
  238. /**
  239. * Posts a callback to run on the next frame.
  240. * <p>
  241. * The callback runs once then is automatically removed.
  242. * </p>
  243. *
  244. * @param callbackType The callback type.
  245. * @param action The callback action to run during the next frame.
  246. * @param token The callback token, or null if none.
  247. *
  248. * @see #removeCallbacks
  249. * @hide
  250. */
  251. public void postCallback(int callbackType, Runnable action, Object token) {
  252. postCallbackDelayed(callbackType, action, token, 0);
  253. }
  254. /**
  255. * Posts a callback to run on the next frame after the specified delay.
  256. * <p>
  257. * The callback runs once then is automatically removed.
  258. * </p>
  259. *
  260. * @param callbackType The callback type.
  261. * @param action The callback action to run during the next frame after the specified delay.
  262. * @param token The callback token, or null if none.
  263. * @param delayMillis The delay time in milliseconds.
  264. *
  265. * @see #removeCallback
  266. * @hide
  267. */
  268. public void postCallbackDelayed(int callbackType,
  269. Runnable action, Object token, long delayMillis) {
  270. if (action == null) {
  271. throw new IllegalArgumentException("action must not be null");
  272. }
  273. if (callbackType < 0 || callbackType > CALLBACK_LAST) {
  274. throw new IllegalArgumentException("callbackType is invalid");
  275. }
  276. postCallbackDelayedInternal(callbackType, action, token, delayMillis);
  277. }
  278. private void postCallbackDelayedInternal(int callbackType,
  279. Object action, Object token, long delayMillis) {
  280. if (DEBUG) {
  281. Log.d(TAG, "PostCallback: type=" + callbackType
  282. + ", action=" + action + ", token=" + token
  283. + ", delayMillis=" + delayMillis);
  284. }
  285. synchronized (mLock) {
  286. final long now = SystemClock.uptimeMillis();
  287. final long dueTime = now + delayMillis;
  288. mCallbackQueues[callbackType].addCallbackLocked(dueTime, action, token);
  289. if (dueTime <= now) {
  290. scheduleFrameLocked(now);
  291. } else {
  292. Message msg = mHandler.obtainMessage(MSG_DO_SCHEDULE_CALLBACK, action);
  293. msg.arg1 = callbackType;
  294. msg.setAsynchronous(true);
  295. mHandler.sendMessageAtTime(msg, dueTime);
  296. }
  297. }
  298. }
  299. /**
  300. * Removes callbacks that have the specified action and token.
  301. *
  302. * @param callbackType The callback type.
  303. * @param action The action property of the callbacks to remove, or null to remove
  304. * callbacks with any action.
  305. * @param token The token property of the callbacks to remove, or null to remove
  306. * callbacks with any token.
  307. *
  308. * @see #postCallback
  309. * @see #postCallbackDelayed
  310. * @hide
  311. */
  312. public void removeCallbacks(int callbackType, Runnable action, Object token) {
  313. if (callbackType < 0 || callbackType > CALLBACK_LAST) {
  314. throw new IllegalArgumentException("callbackType is invalid");
  315. }
  316. removeCallbacksInternal(callbackType, action, token);
  317. }
  318. private void removeCallbacksInternal(int callbackType, Object action, Object token) {
  319. if (DEBUG) {
  320. Log.d(TAG, "RemoveCallbacks: type=" + callbackType
  321. + ", action=" + action + ", token=" + token);
  322. }
  323. synchronized (mLock) {
  324. mCallbackQueues[callbackType].removeCallbacksLocked(action, token);
  325. if (action != null && token == null) {
  326. mHandler.removeMessages(MSG_DO_SCHEDULE_CALLBACK, action);
  327. }
  328. }
  329. }
  330. /**
  331. * Posts a frame callback to run on the next frame.
  332. * <p>
  333. * The callback runs once then is automatically removed.
  334. * </p>
  335. *
  336. * @param callback The frame callback to run during the next frame.
  337. *
  338. * @see #postFrameCallbackDelayed
  339. * @see #removeFrameCallback
  340. */
  341. public void postFrameCallback(FrameCallback callback) {
  342. postFrameCallbackDelayed(callback, 0);
  343. }
  344. /**
  345. * Posts a frame callback to run on the next frame after the specified delay.
  346. * <p>
  347. * The callback runs once then is automatically removed.
  348. * </p>
  349. *
  350. * @param callback The frame callback to run during the next frame.
  351. * @param delayMillis The delay time in milliseconds.
  352. *
  353. * @see #postFrameCallback
  354. * @see #removeFrameCallback
  355. */
  356. public void postFrameCallbackDelayed(FrameCallback callback, long delayMillis) {
  357. if (callback == null) {
  358. throw new IllegalArgumentException("callback must not be null");
  359. }
  360. postCallbackDelayedInternal(CALLBACK_ANIMATION,
  361. callback, FRAME_CALLBACK_TOKEN, delayMillis);
  362. }
  363. /**
  364. * Removes a previously posted frame callback.
  365. *
  366. * @param callback The frame callback to remove.
  367. *
  368. * @see #postFrameCallback
  369. * @see #postFrameCallbackDelayed
  370. */
  371. public void removeFrameCallback(FrameCallback callback) {
  372. if (callback == null) {
  373. throw new IllegalArgumentException("callback must not be null");
  374. }
  375. removeCallbacksInternal(CALLBACK_ANIMATION, callback, FRAME_CALLBACK_TOKEN);
  376. }
  377. /**
  378. * Gets the time when the current frame started.
  379. * <p>
  380. * This method provides the time in nanoseconds when the frame started being rendered.
  381. * The frame time provides a stable time base for synchronizing animations
  382. * and drawing. It should be used instead of {@link SystemClock#uptimeMillis()}
  383. * or {@link System#nanoTime()} for animations and drawing in the UI. Using the frame
  384. * time helps to reduce inter-frame jitter because the frame time is fixed at the time
  385. * the frame was scheduled to start, regardless of when the animations or drawing
  386. * callback actually runs. All callbacks that run as part of rendering a frame will
  387. * observe the same frame time so using the frame time also helps to synchronize effects
  388. * that are performed by different callbacks.
  389. * </p><p>
  390. * Please note that the framework already takes care to process animations and
  391. * drawing using the frame time as a stable time base. Most applications should
  392. * not need to use the frame time information directly.
  393. * </p><p>
  394. * This method should only be called from within a callback.
  395. * </p>
  396. *
  397. * @return The frame start time, in the {@link SystemClock#uptimeMillis()} time base.
  398. *
  399. * @throws IllegalStateException if no frame is in progress.
  400. * @hide
  401. */
  402. public long getFrameTime() {
  403. return getFrameTimeNanos() / NANOS_PER_MS;
  404. }
  405. /**
  406. * Same as {@link #getFrameTime()} but with nanosecond precision.
  407. *
  408. * @return The frame start time, in the {@link System#nanoTime()} time base.
  409. *
  410. * @throws IllegalStateException if no frame is in progress.
  411. * @hide
  412. */
  413. public long getFrameTimeNanos() {
  414. synchronized (mLock) {
  415. if (!mCallbacksRunning) {
  416. throw new IllegalStateException("This method must only be called as "
  417. + "part of a callback while a frame is in progress.");
  418. }
  419. return USE_FRAME_TIME ? mLastFrameTimeNanos : System.nanoTime();
  420. }
  421. }
  422. private void scheduleFrameLocked(long now) {
  423. if (!mFrameScheduled) {
  424. mFrameScheduled = true;
  425. if (USE_VSYNC) {
  426. if (DEBUG) {
  427. Log.d(TAG, "Scheduling next frame on vsync.");
  428. }
  429. // If running on the Looper thread, then schedule the vsync immediately,
  430. // otherwise post a message to schedule the vsync from the UI thread
  431. // as soon as possible.
  432. if (isRunningOnLooperThreadLocked()) {
  433. scheduleVsyncLocked();
  434. } else {
  435. Message msg = mHandler.obtainMessage(MSG_DO_SCHEDULE_VSYNC);
  436. msg.setAsynchronous(true);
  437. mHandler.sendMessageAtFrontOfQueue(msg);
  438. }
  439. } else {
  440. final long nextFrameTime = Math.max(
  441. mLastFrameTimeNanos / NANOS_PER_MS + sFrameDelay, now);
  442. if (DEBUG) {
  443. Log.d(TAG, "Scheduling next frame in " + (nextFrameTime - now) + " ms.");
  444. }
  445. Message msg = mHandler.obtainMessage(MSG_DO_FRAME);
  446. msg.setAsynchronous(true);
  447. mHandler.sendMessageAtTime(msg, nextFrameTime);
  448. }
  449. }
  450. }
  451. void doFrame(long frameTimeNanos, int frame) {
  452. final long startNanos;
  453. synchronized (mLock) {
  454. if (!mFrameScheduled) {
  455. return; // no work to do
  456. }
  457. startNanos = System.nanoTime();
  458. final long jitterNanos = startNanos - frameTimeNanos;
  459. if (jitterNanos >= mFrameIntervalNanos) {
  460. final long skippedFrames = jitterNanos / mFrameIntervalNanos;
  461. if (skippedFrames >= SKIPPED_FRAME_WARNING_LIMIT) {
  462. Log.i(TAG, "Skipped " + skippedFrames + " frames! "
  463. + "The application may be doing too much work on its main thread.");
  464. }
  465. final long lastFrameOffset = jitterNanos % mFrameIntervalNanos;
  466. if (DEBUG) {
  467. Log.d(TAG, "Missed vsync by " + (jitterNanos * 0.000001f) + " ms "
  468. + "which is more than the frame interval of "
  469. + (mFrameIntervalNanos * 0.000001f) + " ms! "
  470. + "Skipping " + skippedFrames + " frames and setting frame "
  471. + "time to " + (lastFrameOffset * 0.000001f) + " ms in the past.");
  472. }
  473. frameTimeNanos = startNanos - lastFrameOffset;
  474. }
  475. if (frameTimeNanos < mLastFrameTimeNanos) {
  476. if (DEBUG) {
  477. Log.d(TAG, "Frame time appears to be going backwards. May be due to a "
  478. + "previously skipped frame. Waiting for next vsync.");
  479. }
  480. scheduleVsyncLocked();
  481. return;
  482. }
  483. mFrameScheduled = false;
  484. mLastFrameTimeNanos = frameTimeNanos;
  485. }
  486. doCallbacks(Choreographer.CALLBACK_INPUT, frameTimeNanos);
  487. doCallbacks(Choreographer.CALLBACK_ANIMATION, frameTimeNanos);
  488. doCallbacks(Choreographer.CALLBACK_TRAVERSAL, frameTimeNanos);
  489. if (DEBUG) {
  490. final long endNanos = System.nanoTime();
  491. Log.d(TAG, "Frame " + frame + ": Finished, took "
  492. + (endNanos - startNanos) * 0.000001f + " ms, latency "
  493. + (startNanos - frameTimeNanos) * 0.000001f + " ms.");
  494. }
  495. }
  496. void doCallbacks(int callbackType, long frameTimeNanos) {
  497. CallbackRecord callbacks;
  498. synchronized (mLock) {
  499. // We use "now" to determine when callbacks become due because it's possible
  500. // for earlier processing phases in a frame to post callbacks that should run
  501. // in a following phase, such as an input event that causes an animation to start.
  502. final long now = SystemClock.uptimeMillis();
  503. callbacks = mCallbackQueues[callbackType].extractDueCallbacksLocked(now);
  504. if (callbacks == null) {
  505. return;
  506. }
  507. mCallbacksRunning = true;
  508. }
  509. try {
  510. for (CallbackRecord c = callbacks; c != null; c = c.next) {
  511. if (DEBUG) {
  512. Log.d(TAG, "RunCallback: type=" + callbackType
  513. + ", action=" + c.action + ", token=" + c.token
  514. + ", latencyMillis=" + (SystemClock.uptimeMillis() - c.dueTime));
  515. }
  516. c.run(frameTimeNanos);
  517. }
  518. } finally {
  519. synchronized (mLock) {
  520. mCallbacksRunning = false;
  521. do {
  522. final CallbackRecord next = callbacks.next;
  523. recycleCallbackLocked(callbacks);
  524. callbacks = next;
  525. } while (callbacks != null);
  526. }
  527. }
  528. }
  529. void doScheduleVsync() {
  530. synchronized (mLock) {
  531. if (mFrameScheduled) {
  532. scheduleVsyncLocked();
  533. }
  534. }
  535. }
  536. void doScheduleCallback(int callbackType) {
  537. synchronized (mLock) {
  538. if (!mFrameScheduled) {
  539. final long now = SystemClock.uptimeMillis();
  540. if (mCallbackQueues[callbackType].hasDueCallbacksLocked(now)) {
  541. scheduleFrameLocked(now);
  542. }
  543. }
  544. }
  545. }
  546. private void scheduleVsyncLocked() {
  547. mDisplayEventReceiver.scheduleVsync();
  548. }
  549. private boolean isRunningOnLooperThreadLocked() {
  550. return Looper.myLooper() == mLooper;
  551. }
  552. private CallbackRecord obtainCallbackLocked(long dueTime, Object action, Object token) {
  553. CallbackRecord callback = mCallbackPool;
  554. if (callback == null) {
  555. callback = new CallbackRecord();
  556. } else {
  557. mCallbackPool = callback.next;
  558. callback.next = null;
  559. }
  560. callback.dueTime = dueTime;
  561. callback.action = action;
  562. callback.token = token;
  563. return callback;
  564. }
  565. private void recycleCallbackLocked(CallbackRecord callback) {
  566. callback.action = null;
  567. callback.token = null;
  568. callback.next = mCallbackPool;
  569. mCallbackPool = callback;
  570. }
  571. /**
  572. * Implement this interface to receive a callback when a new display frame is
  573. * being rendered. The callback is invoked on the {@link Looper} thread to
  574. * which the {@link Choreographer} is attached.
  575. */
  576. public interface FrameCallback {
  577. /**
  578. * Called when a new display frame is being rendered.
  579. * <p>
  580. * This method provides the time in nanoseconds when the frame started being rendered.
  581. * The frame time provides a stable time base for synchronizing animations
  582. * and drawing. It should be used instead of {@link SystemClock#uptimeMillis()}
  583. * or {@link System#nanoTime()} for animations and drawing in the UI. Using the frame
  584. * time helps to reduce inter-frame jitter because the frame time is fixed at the time
  585. * the frame was scheduled to start, regardless of when the animations or drawing
  586. * callback actually runs. All callbacks that run as part of rendering a frame will
  587. * observe the same frame time so using the frame time also helps to synchronize effects
  588. * that are performed by different callbacks.
  589. * </p><p>
  590. * Please note that the framework already takes care to process animations and
  591. * drawing using the frame time as a stable time base. Most applications should
  592. * not need to use the frame time information directly.
  593. * </p>
  594. *
  595. * @param frameTimeNanos The time in nanoseconds when the frame started being rendered,
  596. * in the {@link System#nanoTime()} timebase. Divide this value by {@code 1000000}
  597. * to convert it to the {@link SystemClock#uptimeMillis()} time base.
  598. */
  599. public void doFrame(long frameTimeNanos);
  600. }
  601. private final class FrameHandler extends Handler {
  602. public FrameHandler(Looper looper) {
  603. super(looper);
  604. }
  605. @Override
  606. public void handleMessage(Message msg) {
  607. switch (msg.what) {
  608. case MSG_DO_FRAME:
  609. doFrame(System.nanoTime(), 0);
  610. break;
  611. case MSG_DO_SCHEDULE_VSYNC:
  612. doScheduleVsync();
  613. break;
  614. case MSG_DO_SCHEDULE_CALLBACK:
  615. doScheduleCallback(msg.arg1);
  616. break;
  617. }
  618. }
  619. }
  620. private final class FrameDisplayEventReceiver extends DisplayEventReceiver
  621. implements Runnable {
  622. private boolean mHavePendingVsync;
  623. private long mTimestampNanos;
  624. private int mFrame;
  625. public FrameDisplayEventReceiver(Looper looper) {
  626. super(looper);
  627. }
  628. @Override
  629. public void onVsync(long timestampNanos, int builtInDisplayId, int frame) {
  630. // Ignore vsync from secondary display.
  631. // This can be problematic because the call to scheduleVsync() is a one-shot.
  632. // We need to ensure that we will still receive the vsync from the primary
  633. // display which is the one we really care about. Ideally we should schedule
  634. // vsync for a particular display.
  635. // At this time Surface Flinger won't send us vsyncs for secondary displays
  636. // but that could change in the future so let's log a message to help us remember
  637. // that we need to fix this.
  638. if (builtInDisplayId != SurfaceControl.BUILT_IN_DISPLAY_ID_MAIN) {
  639. Log.d(TAG, "Received vsync from secondary display, but we don't support "
  640. + "this case yet. Choreographer needs a way to explicitly request "
  641. + "vsync for a specific display to ensure it doesn't lose track "
  642. + "of its scheduled vsync.");
  643. scheduleVsync();
  644. return;
  645. }
  646. // Post the vsync event to the Handler.
  647. // The idea is to prevent incoming vsync events from completely starving
  648. // the message queue. If there are no messages in the queue with timestamps
  649. // earlier than the frame time, then the vsync event will be processed immediately.
  650. // Otherwise, messages that predate the vsync event will be handled first.
  651. long now = System.nanoTime();
  652. if (timestampNanos > now) {
  653. Log.w(TAG, "Frame time is " + ((timestampNanos - now) * 0.000001f)
  654. + " ms in the future! Check that graphics HAL is generating vsync "
  655. + "timestamps using the correct timebase.");
  656. timestampNanos = now;
  657. }
  658. if (mHavePendingVsync) {
  659. Log.w(TAG, "Already have a pending vsync event. There should only be "
  660. + "one at a time.");
  661. } else {
  662. mHavePendingVsync = true;
  663. }
  664. mTimestampNanos = timestampNanos;
  665. mFrame = frame;
  666. Message msg = Message.obtain(mHandler, this);
  667. msg.setAsynchronous(true);
  668. mHandler.sendMessageAtTime(msg, timestampNanos / NANOS_PER_MS);
  669. }
  670. @Override
  671. public void run() {
  672. mHavePendingVsync = false;
  673. doFrame(mTimestampNanos, mFrame);
  674. }
  675. }
  676. private static final class CallbackRecord {
  677. public CallbackRecord next;
  678. public long dueTime;
  679. public Object action; // Runnable or FrameCallback
  680. public Object token;
  681. public void run(long frameTimeNanos) {
  682. if (token == FRAME_CALLBACK_TOKEN) {
  683. ((FrameCallback)action).doFrame(frameTimeNanos);
  684. } else {
  685. ((Runnable)action).run();
  686. }
  687. }
  688. }
  689. private final class CallbackQueue {
  690. private CallbackRecord mHead;
  691. public boolean hasDueCallbacksLocked(long now) {
  692. return mHead != null && mHead.dueTime <= now;
  693. }
  694. public CallbackRecord extractDueCallbacksLocked(long now) {
  695. CallbackRecord callbacks = mHead;
  696. if (callbacks == null || callbacks.dueTime > now) {
  697. return null;
  698. }
  699. CallbackRecord last = callbacks;
  700. CallbackRecord next = last.next;
  701. while (next != null) {
  702. if (next.dueTime > now) {
  703. last.next = null;
  704. break;
  705. }
  706. last = next;
  707. next = next.next;
  708. }
  709. mHead = next;
  710. return callbacks;
  711. }
  712. public void addCallbackLocked(long dueTime, Object action, Object token) {
  713. CallbackRecord callback = obtainCallbackLocked(dueTime, action, token);
  714. CallbackRecord entry = mHead;
  715. if (entry == null) {
  716. mHead = callback;
  717. return;
  718. }
  719. if (dueTime < entry.dueTime) {
  720. callback.next = entry;
  721. mHead = callback;
  722. return;
  723. }
  724. while (entry.next != null) {
  725. if (dueTime < entry.next.dueTime) {
  726. callback.next = entry.next;
  727. break;
  728. }
  729. entry = entry.next;
  730. }
  731. entry.next = callback;
  732. }
  733. public void removeCallbacksLocked(Object action, Object token) {
  734. CallbackRecord predecessor = null;
  735. for (CallbackRecord callback = mHead; callback != null;) {
  736. final CallbackRecord next = callback.next;
  737. if ((action == null || callback.action == action)
  738. && (token == null || callback.token == token)) {
  739. if (predecessor != null) {
  740. predecessor.next = next;
  741. } else {
  742. mHead = next;
  743. }
  744. recycleCallbackLocked(callback);
  745. } else {
  746. predecessor = callback;
  747. }
  748. callback = next;
  749. }
  750. }
  751. }
  752. }