core/java/android/view/Choreographer.java - platform/frameworks/base - Gitiles

 /*
  * Copyright (C) 2011 The Android Open Source Project
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
  * You may obtain a copy of the License at
  *
  *      http://www.apache.org/licenses/LICENSE-2.0
  *
  * Unless required by applicable law or agreed to in writing, software
  * distributed under the License is distributed on an "AS IS" BASIS,
  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  * See the License for the specific language governing permissions and
  * limitations under the License.
  */

 package android.view;

 import android.os.Handler;
 import android.os.Looper;
 import android.os.Message;
 import android.os.SystemClock;
 import android.os.SystemProperties;
 import android.util.Log;

 /**
  * Coordinates animations and drawing for UI on a particular thread.
  *
  * This object is thread-safe.  Other threads can post callbacks to run at a later time
  * on the UI thread.
  *
  * Ensuring thread-safety is a little tricky because the {@link DisplayEventReceiver}
  * can only be accessed from the UI thread so operations that touch the event receiver
  * are posted to the UI thread if needed.
  *
  * @hide
  */
 public final class Choreographer {
     private static final String TAG = "Choreographer";
     private static final boolean DEBUG = false;

     // The default amount of time in ms between animation frames.
     // When vsync is not enabled, we want to have some idea of how long we should
     // wait before posting the next animation message.  It is important that the
     // default value be less than the true inter-frame delay on all devices to avoid
     // situations where we might skip frames by waiting too long (we must compensate
     // for jitter and hardware variations).  Regardless of this value, the animation
     // and display loop is ultimately rate-limited by how fast new graphics buffers can
     // be dequeued.
     private static final long DEFAULT_FRAME_DELAY = 10;

     // The number of milliseconds between animation frames.
     private static volatile long sFrameDelay = DEFAULT_FRAME_DELAY;

     // Thread local storage for the choreographer.
     private static final ThreadLocal<Choreographer> sThreadInstance =
             new ThreadLocal<Choreographer>() {
         @Override
         protected Choreographer initialValue() {
             Looper looper = Looper.myLooper();
             if (looper == null) {
                 throw new IllegalStateException("The current thread must have a looper!");
             }
             return new Choreographer(looper);
         }
     };

     // System property to enable/disable vsync for animations and drawing.
     // Enabled by default.
     private static final boolean USE_VSYNC = SystemProperties.getBoolean(
             "debug.choreographer.vsync", true);

     // System property to enable/disable the use of the vsync / animation timer
     // for drawing rather than drawing immediately.
     // Temporarily disabled by default because postponing performTraversals() violates
     // assumptions about traversals happening in-order relative to other posted messages.
     // Bug: 5721047
     private static final boolean USE_ANIMATION_TIMER_FOR_DRAW = SystemProperties.getBoolean(
             "debug.choreographer.animdraw", false);

     private static final int MSG_DO_ANIMATION = 0;
     private static final int MSG_DO_DRAW = 1;
     private static final int MSG_DO_SCHEDULE_VSYNC = 2;
     private static final int MSG_DO_SCHEDULE_ANIMATION = 3;
     private static final int MSG_DO_SCHEDULE_DRAW = 4;

     private final Object mLock = new Object();

     private final Looper mLooper;
     private final FrameHandler mHandler;
     private final FrameDisplayEventReceiver mDisplayEventReceiver;

     private Callback mCallbackPool;

     private final CallbackQueue mAnimationCallbackQueue = new CallbackQueue();
     private final CallbackQueue mDrawCallbackQueue = new CallbackQueue();

     private boolean mAnimationScheduled;
     private boolean mDrawScheduled;
     private long mLastAnimationTime;
     private long mLastDrawTime;

     private Choreographer(Looper looper) {
         mLooper = looper;
         mHandler = new FrameHandler(looper);
         mDisplayEventReceiver = USE_VSYNC ? new FrameDisplayEventReceiver(looper) : null;
         mLastAnimationTime = Long.MIN_VALUE;
         mLastDrawTime = Long.MIN_VALUE;
     }

     /**
      * Gets the choreographer for the calling thread.  Must be called from
      * a thread that already has a {@link android.os.Looper} associated with it.
      *
      * @return The choreographer for this thread.
      * @throws IllegalStateException if the thread does not have a looper.
      */
     public static Choreographer getInstance() {
         return sThreadInstance.get();
     }

     /**
      * The amount of time, in milliseconds, between each frame of the animation. This is a
      * requested time that the animation will attempt to honor, but the actual delay between
      * frames may be different, depending on system load and capabilities. This is a static
      * function because the same delay will be applied to all animations, since they are all
      * run off of a single timing loop.
      *
      * The frame delay may be ignored when the animation system uses an external timing
      * source, such as the display refresh rate (vsync), to govern animations.
      *
      * @return the requested time between frames, in milliseconds
      */
     public static long getFrameDelay() {
         return sFrameDelay;
     }

     /**
      * The amount of time, in milliseconds, between each frame of the animation. This is a
      * requested time that the animation will attempt to honor, but the actual delay between
      * frames may be different, depending on system load and capabilities. This is a static
      * function because the same delay will be applied to all animations, since they are all
      * run off of a single timing loop.
      *
      * The frame delay may be ignored when the animation system uses an external timing
      * source, such as the display refresh rate (vsync), to govern animations.
      *
      * @param frameDelay the requested time between frames, in milliseconds
      */
     public static void setFrameDelay(long frameDelay) {
         sFrameDelay = frameDelay;
     }

     /**
      * Subtracts typical frame delay time from a delay interval in milliseconds.
      *
      * This method can be used to compensate for animation delay times that have baked
      * in assumptions about the frame delay.  For example, it's quite common for code to
      * assume a 60Hz frame time and bake in a 16ms delay.  When we call
      * {@link #postAnimationCallbackDelayed} we want to know how long to wait before
      * posting the animation callback but let the animation timer take care of the remaining
      * frame delay time.
      *
      * This method is somewhat conservative about how much of the frame delay it
      * subtracts.  It uses the same value returned by {@link #getFrameDelay} which by
      * default is 10ms even though many parts of the system assume 16ms.  Consequently,
      * we might still wait 6ms before posting an animation callback that we want to run
      * on the next frame, but this is much better than waiting a whole 16ms and likely
      * missing the deadline.
      *
      * @param delayMillis The original delay time including an assumed frame delay.
      * @return The adjusted delay time with the assumed frame delay subtracted out.
      */
     public static long subtractFrameDelay(long delayMillis) {
         final long frameDelay = sFrameDelay;
         return delayMillis <= frameDelay ? 0 : delayMillis - frameDelay;
     }

     /**
      * Posts a callback to run on the next animation cycle.
      * The callback only runs once and then is automatically removed.
      *
      * @param action The callback action to run during the next animation cycle.
      * @param token The callback token, or null if none.
      *
      * @see #removeAnimationCallback
      */
     public void postAnimationCallback(Runnable action, Object token) {
         postAnimationCallbackDelayed(action, token, 0);
     }

     /**
      * Posts a callback to run on the next animation cycle following the specified delay.
      * The callback only runs once and then is automatically removed.
      *
      * @param action The callback action to run during the next animation cycle after
      * the specified delay.
      * @param token The callback token, or null if none.
      * @param delayMillis The delay time in milliseconds.
      *
      * @see #removeAnimationCallback
      */
     public void postAnimationCallbackDelayed(Runnable action, Object token, long delayMillis) {
         if (action == null) {
             throw new IllegalArgumentException("action must not be null");
         }

         if (DEBUG) {
             Log.d(TAG, "PostAnimationCallback: " + action + ", token=" + token
                     + ", delayMillis=" + delayMillis);
         }

         synchronized (mLock) {
             final long now = SystemClock.uptimeMillis();
             final long dueTime = now + delayMillis;
             mAnimationCallbackQueue.addCallbackLocked(dueTime, action, token);

             if (dueTime <= now) {
                 scheduleAnimationLocked(now);
             } else {
                 Message msg = mHandler.obtainMessage(MSG_DO_SCHEDULE_ANIMATION, action);
                 mHandler.sendMessageAtTime(msg, dueTime);
             }
         }
     }

     /**
      * Removes animation callbacks that have the specified action and token.
      *
      * @param action The action property of the callbacks to remove, or null to remove
      * callbacks with any action.
      * @param token The token property of the callbacks to remove, or null to remove
      * callbacks with any token.
      *
      * @see #postAnimationCallback
      * @see #postAnimationCallbackDelayed
      */
     public void removeAnimationCallbacks(Runnable action, Object token) {
         if (DEBUG) {
             Log.d(TAG, "RemoveAnimationCallbacks: " + action + ", token=" + token);
         }

         synchronized (mLock) {
             mAnimationCallbackQueue.removeCallbacksLocked(action, token);
             if (action != null && token == null) {
                 mHandler.removeMessages(MSG_DO_SCHEDULE_ANIMATION, action);
             }
         }
     }

     /**
      * Posts a callback to run on the next draw cycle.
      * The callback only runs once and then is automatically removed.
      *
      * @param action The callback action to run during the next draw cycle.
      * @param token The callback token, or null if none.
      *
      * @see #removeDrawCallback
      */
     public void postDrawCallback(Runnable action, Object token) {
         postDrawCallbackDelayed(action, token, 0);
     }

     /**
      * Posts a callback to run on the next draw cycle following the specified delay.
      * The callback only runs once and then is automatically removed.
      *
      * @param action The callback action to run during the next animation cycle after
      * the specified delay.
      * @param token The callback token, or null if none.
      * @param delayMillis The delay time in milliseconds.
      *
      * @see #removeDrawCallback
      */
     public void postDrawCallbackDelayed(Runnable action, Object token, long delayMillis) {
         if (action == null) {
             throw new IllegalArgumentException("action must not be null");
         }

         if (DEBUG) {
             Log.d(TAG, "PostDrawCallback: " + action + ", token=" + token
                     + ", delayMillis=" + delayMillis);
         }

         synchronized (mLock) {
             final long now = SystemClock.uptimeMillis();
             final long dueTime = now + delayMillis;
             mDrawCallbackQueue.addCallbackLocked(dueTime, action, token);
             scheduleDrawLocked(now);

             if (dueTime <= now) {
                 scheduleDrawLocked(now);
             } else {
                 Message msg = mHandler.obtainMessage(MSG_DO_SCHEDULE_DRAW, action);
                 mHandler.sendMessageAtTime(msg, dueTime);
             }
         }
     }

     /**
      * Removes draw callbacks that have the specified action and token.
      *
      * @param action The action property of the callbacks to remove, or null to remove
      * callbacks with any action.
      * @param token The token property of the callbacks to remove, or null to remove
      * callbacks with any token.
      *
      * @see #postDrawCallback
      * @see #postDrawCallbackDelayed
      */
     public void removeDrawCallbacks(Runnable action, Object token) {
         if (DEBUG) {
             Log.d(TAG, "RemoveDrawCallbacks: " + action + ", token=" + token);
         }

         synchronized (mLock) {
             mDrawCallbackQueue.removeCallbacksLocked(action, token);
             if (action != null && token == null) {
                 mHandler.removeMessages(MSG_DO_SCHEDULE_DRAW, action);
             }
         }
     }

     private void scheduleAnimationLocked(long now) {
         if (!mAnimationScheduled) {
             mAnimationScheduled = true;
             if (USE_VSYNC) {
                 if (DEBUG) {
                     Log.d(TAG, "Scheduling vsync for animation.");
                 }

                 // If running on the Looper thread, then schedule the vsync immediately,
                 // otherwise post a message to schedule the vsync from the UI thread
                 // as soon as possible.
                 if (isRunningOnLooperThreadLocked()) {
                     scheduleVsyncLocked();
                 } else {
                     Message msg = mHandler.obtainMessage(MSG_DO_SCHEDULE_VSYNC);
                     msg.setAsynchronous(true);
                     mHandler.sendMessageAtFrontOfQueue(msg);
                 }
             } else {
                 final long nextAnimationTime = Math.max(mLastAnimationTime + sFrameDelay, now);
                 if (DEBUG) {
                     Log.d(TAG, "Scheduling animation in " + (nextAnimationTime - now) + " ms.");
                 }
                 Message msg = mHandler.obtainMessage(MSG_DO_ANIMATION);
                 msg.setAsynchronous(true);
                 mHandler.sendMessageAtTime(msg, nextAnimationTime);
             }
         }
     }

     private void scheduleDrawLocked(long now) {
         if (!mDrawScheduled) {
             mDrawScheduled = true;
             if (USE_ANIMATION_TIMER_FOR_DRAW) {
                 scheduleAnimationLocked(now);
             } else {
                 if (DEBUG) {
                     Log.d(TAG, "Scheduling draw immediately.");
                 }
                 Message msg = mHandler.obtainMessage(MSG_DO_DRAW);
                 msg.setAsynchronous(true);
                 mHandler.sendMessageAtTime(msg, now);
             }
         }
     }

     void doAnimation() {
         doAnimationInner();

         if (USE_ANIMATION_TIMER_FOR_DRAW) {
             doDraw();
         }
     }

     void doAnimationInner() {
         final long start;
         Callback callbacks;
         synchronized (mLock) {
             if (!mAnimationScheduled) {
                 return; // no work to do
             }
             mAnimationScheduled = false;

             start = SystemClock.uptimeMillis();
             if (DEBUG) {
                 Log.d(TAG, "Performing animation: " + Math.max(0, start - mLastAnimationTime)
                         + " ms have elapsed since previous animation.");
             }
             mLastAnimationTime = start;

             callbacks = mAnimationCallbackQueue.extractDueCallbacksLocked(start);
         }

         if (callbacks != null) {
             runCallbacks(callbacks);
             synchronized (mLock) {
                 recycleCallbacksLocked(callbacks);
             }
         }

         if (DEBUG) {
             Log.d(TAG, "Animation took " + (SystemClock.uptimeMillis() - start) + " ms.");
         }
     }

     void doDraw() {
         final long start;
         Callback callbacks;
         synchronized (mLock) {
             if (!mDrawScheduled) {
                 return; // no work to do
             }
             mDrawScheduled = false;

             start = SystemClock.uptimeMillis();
             if (DEBUG) {
                 Log.d(TAG, "Performing draw: " + Math.max(0, start - mLastDrawTime)
                         + " ms have elapsed since previous draw.");
             }
             mLastDrawTime = start;

             callbacks = mDrawCallbackQueue.extractDueCallbacksLocked(start);
         }

         if (callbacks != null) {
             runCallbacks(callbacks);
             synchronized (mLock) {
                 recycleCallbacksLocked(callbacks);
             }
         }

         if (DEBUG) {
             Log.d(TAG, "Draw took " + (SystemClock.uptimeMillis() - start) + " ms.");
         }
     }

     void doScheduleVsync() {
         synchronized (mLock) {
             if (mAnimationScheduled) {
                 scheduleVsyncLocked();
             }
         }
     }

     void doScheduleAnimation() {
         synchronized (mLock) {
             final long now = SystemClock.uptimeMillis();
             if (mAnimationCallbackQueue.hasDueCallbacksLocked(now)) {
                 scheduleAnimationLocked(now);
             }
         }
     }

     void doScheduleDraw() {
         synchronized (mLock) {
             final long now = SystemClock.uptimeMillis();
             if (mDrawCallbackQueue.hasDueCallbacksLocked(now)) {
                 scheduleDrawLocked(now);
             }
         }
     }

     private void scheduleVsyncLocked() {
         mDisplayEventReceiver.scheduleVsync();
     }

     private boolean isRunningOnLooperThreadLocked() {
         return Looper.myLooper() == mLooper;
     }

     private void runCallbacks(Callback head) {
         while (head != null) {
             if (DEBUG) {
                 Log.d(TAG, "RunCallback: " + head.action + ", token=" + head.token
                         + ", waitMillis=" + (SystemClock.uptimeMillis() - head.dueTime));
             }
             head.action.run();
             head = head.next;
         }
     }

     private void recycleCallbacksLocked(Callback head) {
         while (head != null) {
             final Callback next = head.next;
             recycleCallbackLocked(head);
             head = next;
         }
     }

     private Callback obtainCallbackLocked(long dueTime, Runnable action, Object token) {
         Callback callback = mCallbackPool;
         if (callback == null) {
             callback = new Callback();
         } else {
             mCallbackPool = callback.next;
             callback.next = null;
         }
         callback.dueTime = dueTime;
         callback.action = action;
         callback.token = token;
         return callback;
     }

     private void recycleCallbackLocked(Callback callback) {
         callback.action = null;
         callback.token = null;
         callback.next = mCallbackPool;
         mCallbackPool = callback;
     }

     private final class FrameHandler extends Handler {
         public FrameHandler(Looper looper) {
             super(looper);
         }

         @Override
         public void handleMessage(Message msg) {
             switch (msg.what) {
                 case MSG_DO_ANIMATION:
                     doAnimation();
                     break;
                 case MSG_DO_DRAW:
                     doDraw();
                     break;
                 case MSG_DO_SCHEDULE_VSYNC:
                     doScheduleVsync();
                     break;
                 case MSG_DO_SCHEDULE_ANIMATION:
                     doScheduleAnimation();
                     break;
                 case MSG_DO_SCHEDULE_DRAW:
                     doScheduleDraw();
                     break;
             }
         }
     }

     private final class FrameDisplayEventReceiver extends DisplayEventReceiver {
         public FrameDisplayEventReceiver(Looper looper) {
             super(looper);
         }

         @Override
         public void onVsync(long timestampNanos, int frame) {
             doAnimation();
         }
     }

     private static final class Callback {
         public Callback next;
         public long dueTime;
         public Runnable action;
         public Object token;
     }

     private final class CallbackQueue {
         private Callback mHead;

         public boolean hasDueCallbacksLocked(long now) {
             return mHead != null && mHead.dueTime <= now;
         }

         public Callback extractDueCallbacksLocked(long now) {
             Callback callbacks = mHead;
             if (callbacks == null || callbacks.dueTime > now) {
                 return null;
             }

             Callback last = callbacks;
             Callback next = last.next;
             while (next != null) {
                 if (next.dueTime > now) {
                     last.next = null;
                     break;
                 }
                 last = next;
                 next = next.next;
             }
             mHead = next;
             return callbacks;
         }

         public void addCallbackLocked(long dueTime, Runnable action, Object token) {
             Callback callback = obtainCallbackLocked(dueTime, action, token);
             Callback entry = mHead;
             if (entry == null) {
                 mHead = callback;
                 return;
             }
             if (dueTime < entry.dueTime) {
                 callback.next = entry;
                 mHead = callback;
                 return;
             }
             while (entry.next != null) {
                 if (dueTime < entry.next.dueTime) {
                     callback.next = entry.next;
                     break;
                 }
                 entry = entry.next;
             }
             entry.next = callback;
         }

         public void removeCallbacksLocked(Runnable action, Object token) {
             Callback predecessor = null;
             for (Callback callback = mHead; callback != null;) {
                 final Callback next = callback.next;
                 if ((action == null || callback.action == action)
                         && (token == null || callback.token == token)) {
                     if (predecessor != null) {
                         predecessor.next = next;
                     } else {
                         mHead = next;
                     }
                     recycleCallbackLocked(callback);
                 } else {
                     predecessor = callback;
                 }
                 callback = next;
             }
         }
     }
 }
	/*
	* Copyright (C) 2011 The Android Open Source Project
	*
	* Licensed under the Apache License, Version 2.0 (the "License");
	* you may not use this file except in compliance with the License.
	* You may obtain a copy of the License at
	*
	* http://www.apache.org/licenses/LICENSE-2.0
	*
	* Unless required by applicable law or agreed to in writing, software
	* distributed under the License is distributed on an "AS IS" BASIS,
	* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
	* See the License for the specific language governing permissions and
	* limitations under the License.
	*/

	package android.view;

	import android.os.Handler;
	import android.os.Looper;
	import android.os.Message;
	import android.os.SystemClock;
	import android.os.SystemProperties;
	import android.util.Log;

	/**
	* Coordinates animations and drawing for UI on a particular thread.
	*
	* This object is thread-safe. Other threads can post callbacks to run at a later time
	* on the UI thread.
	*
	* Ensuring thread-safety is a little tricky because the {@link DisplayEventReceiver}
	* can only be accessed from the UI thread so operations that touch the event receiver
	* are posted to the UI thread if needed.
	*
	* @hide
	*/
	public final class Choreographer {
	private static final String TAG = "Choreographer";
	private static final boolean DEBUG = false;

	// The default amount of time in ms between animation frames.
	// When vsync is not enabled, we want to have some idea of how long we should
	// wait before posting the next animation message. It is important that the
	// default value be less than the true inter-frame delay on all devices to avoid
	// situations where we might skip frames by waiting too long (we must compensate
	// for jitter and hardware variations). Regardless of this value, the animation
	// and display loop is ultimately rate-limited by how fast new graphics buffers can
	// be dequeued.
	private static final long DEFAULT_FRAME_DELAY = 10;

	// The number of milliseconds between animation frames.
	private static volatile long sFrameDelay = DEFAULT_FRAME_DELAY;

	// Thread local storage for the choreographer.
	private static final ThreadLocal<Choreographer> sThreadInstance =
	new ThreadLocal<Choreographer>() {
	@Override
	protected Choreographer initialValue() {
	Looper looper = Looper.myLooper();
	if (looper == null) {
	throw new IllegalStateException("The current thread must have a looper!");
	}
	return new Choreographer(looper);
	}
	};

	// System property to enable/disable vsync for animations and drawing.
	// Enabled by default.
	private static final boolean USE_VSYNC = SystemProperties.getBoolean(
	"debug.choreographer.vsync", true);

	// System property to enable/disable the use of the vsync / animation timer
	// for drawing rather than drawing immediately.
	// Temporarily disabled by default because postponing performTraversals() violates
	// assumptions about traversals happening in-order relative to other posted messages.
	// Bug: 5721047
	private static final boolean USE_ANIMATION_TIMER_FOR_DRAW = SystemProperties.getBoolean(
	"debug.choreographer.animdraw", false);

	private static final int MSG_DO_ANIMATION = 0;
	private static final int MSG_DO_DRAW = 1;
	private static final int MSG_DO_SCHEDULE_VSYNC = 2;
	private static final int MSG_DO_SCHEDULE_ANIMATION = 3;
	private static final int MSG_DO_SCHEDULE_DRAW = 4;

	private final Object mLock = new Object();

	private final Looper mLooper;
	private final FrameHandler mHandler;
	private final FrameDisplayEventReceiver mDisplayEventReceiver;

	private Callback mCallbackPool;

	private final CallbackQueue mAnimationCallbackQueue = new CallbackQueue();
	private final CallbackQueue mDrawCallbackQueue = new CallbackQueue();

	private boolean mAnimationScheduled;
	private boolean mDrawScheduled;
	private long mLastAnimationTime;
	private long mLastDrawTime;

	private Choreographer(Looper looper) {
	mLooper = looper;
	mHandler = new FrameHandler(looper);
	mDisplayEventReceiver = USE_VSYNC ? new FrameDisplayEventReceiver(looper) : null;
	mLastAnimationTime = Long.MIN_VALUE;
	mLastDrawTime = Long.MIN_VALUE;
	}

	/**
	* Gets the choreographer for the calling thread. Must be called from
	* a thread that already has a {@link android.os.Looper} associated with it.
	*
	* @return The choreographer for this thread.
	* @throws IllegalStateException if the thread does not have a looper.
	*/
	public static Choreographer getInstance() {
	return sThreadInstance.get();
	}

	/**
	* The amount of time, in milliseconds, between each frame of the animation. This is a
	* requested time that the animation will attempt to honor, but the actual delay between
	* frames may be different, depending on system load and capabilities. This is a static
	* function because the same delay will be applied to all animations, since they are all
	* run off of a single timing loop.
	*
	* The frame delay may be ignored when the animation system uses an external timing
	* source, such as the display refresh rate (vsync), to govern animations.
	*
	* @return the requested time between frames, in milliseconds
	*/
	public static long getFrameDelay() {
	return sFrameDelay;
	}

	/**
	* The amount of time, in milliseconds, between each frame of the animation. This is a
	* requested time that the animation will attempt to honor, but the actual delay between
	* frames may be different, depending on system load and capabilities. This is a static
	* function because the same delay will be applied to all animations, since they are all
	* run off of a single timing loop.
	*
	* The frame delay may be ignored when the animation system uses an external timing
	* source, such as the display refresh rate (vsync), to govern animations.
	*
	* @param frameDelay the requested time between frames, in milliseconds
	*/
	public static void setFrameDelay(long frameDelay) {
	sFrameDelay = frameDelay;
	}

	/**
	* Subtracts typical frame delay time from a delay interval in milliseconds.
	*
	* This method can be used to compensate for animation delay times that have baked
	* in assumptions about the frame delay. For example, it's quite common for code to
	* assume a 60Hz frame time and bake in a 16ms delay. When we call
	* {@link #postAnimationCallbackDelayed} we want to know how long to wait before
	* posting the animation callback but let the animation timer take care of the remaining
	* frame delay time.
	*
	* This method is somewhat conservative about how much of the frame delay it
	* subtracts. It uses the same value returned by {@link #getFrameDelay} which by
	* default is 10ms even though many parts of the system assume 16ms. Consequently,
	* we might still wait 6ms before posting an animation callback that we want to run
	* on the next frame, but this is much better than waiting a whole 16ms and likely
	* missing the deadline.
	*
	* @param delayMillis The original delay time including an assumed frame delay.
	* @return The adjusted delay time with the assumed frame delay subtracted out.
	*/
	public static long subtractFrameDelay(long delayMillis) {
	final long frameDelay = sFrameDelay;
	return delayMillis <= frameDelay ? 0 : delayMillis - frameDelay;
	}

	/**
	* Posts a callback to run on the next animation cycle.
	* The callback only runs once and then is automatically removed.
	*
	* @param action The callback action to run during the next animation cycle.
	* @param token The callback token, or null if none.
	*
	* @see #removeAnimationCallback
	*/
	public void postAnimationCallback(Runnable action, Object token) {
	postAnimationCallbackDelayed(action, token, 0);
	}

	/**
	* Posts a callback to run on the next animation cycle following the specified delay.
	* The callback only runs once and then is automatically removed.
	*
	* @param action The callback action to run during the next animation cycle after
	* the specified delay.
	* @param token The callback token, or null if none.
	* @param delayMillis The delay time in milliseconds.
	*
	* @see #removeAnimationCallback
	*/
	public void postAnimationCallbackDelayed(Runnable action, Object token, long delayMillis) {
	if (action == null) {
	throw new IllegalArgumentException("action must not be null");
	}

	if (DEBUG) {
	Log.d(TAG, "PostAnimationCallback: " + action + ", token=" + token
	+ ", delayMillis=" + delayMillis);
	}

	synchronized (mLock) {
	final long now = SystemClock.uptimeMillis();
	final long dueTime = now + delayMillis;
	mAnimationCallbackQueue.addCallbackLocked(dueTime, action, token);

	if (dueTime <= now) {
	scheduleAnimationLocked(now);
	} else {
	Message msg = mHandler.obtainMessage(MSG_DO_SCHEDULE_ANIMATION, action);
	mHandler.sendMessageAtTime(msg, dueTime);
	}
	}
	}

	/**
	* Removes animation callbacks that have the specified action and token.
	*
	* @param action The action property of the callbacks to remove, or null to remove
	* callbacks with any action.
	* @param token The token property of the callbacks to remove, or null to remove
	* callbacks with any token.
	*
	* @see #postAnimationCallback
	* @see #postAnimationCallbackDelayed
	*/
	public void removeAnimationCallbacks(Runnable action, Object token) {
	if (DEBUG) {
	Log.d(TAG, "RemoveAnimationCallbacks: " + action + ", token=" + token);
	}

	synchronized (mLock) {
	mAnimationCallbackQueue.removeCallbacksLocked(action, token);
	if (action != null && token == null) {
	mHandler.removeMessages(MSG_DO_SCHEDULE_ANIMATION, action);
	}
	}
	}

	/**
	* Posts a callback to run on the next draw cycle.
	* The callback only runs once and then is automatically removed.
	*
	* @param action The callback action to run during the next draw cycle.
	* @param token The callback token, or null if none.
	*
	* @see #removeDrawCallback
	*/
	public void postDrawCallback(Runnable action, Object token) {
	postDrawCallbackDelayed(action, token, 0);
	}

	/**
	* Posts a callback to run on the next draw cycle following the specified delay.
	* The callback only runs once and then is automatically removed.
	*
	* @param action The callback action to run during the next animation cycle after
	* the specified delay.
	* @param token The callback token, or null if none.
	* @param delayMillis The delay time in milliseconds.
	*
	* @see #removeDrawCallback
	*/
	public void postDrawCallbackDelayed(Runnable action, Object token, long delayMillis) {
	if (action == null) {
	throw new IllegalArgumentException("action must not be null");
	}

	if (DEBUG) {
	Log.d(TAG, "PostDrawCallback: " + action + ", token=" + token
	+ ", delayMillis=" + delayMillis);
	}

	synchronized (mLock) {
	final long now = SystemClock.uptimeMillis();
	final long dueTime = now + delayMillis;
	mDrawCallbackQueue.addCallbackLocked(dueTime, action, token);
	scheduleDrawLocked(now);

	if (dueTime <= now) {
	scheduleDrawLocked(now);
	} else {
	Message msg = mHandler.obtainMessage(MSG_DO_SCHEDULE_DRAW, action);
	mHandler.sendMessageAtTime(msg, dueTime);
	}
	}
	}

	/**
	* Removes draw callbacks that have the specified action and token.
	*
	* @param action The action property of the callbacks to remove, or null to remove
	* callbacks with any action.
	* @param token The token property of the callbacks to remove, or null to remove
	* callbacks with any token.
	*
	* @see #postDrawCallback
	* @see #postDrawCallbackDelayed
	*/
	public void removeDrawCallbacks(Runnable action, Object token) {
	if (DEBUG) {
	Log.d(TAG, "RemoveDrawCallbacks: " + action + ", token=" + token);
	}

	synchronized (mLock) {
	mDrawCallbackQueue.removeCallbacksLocked(action, token);
	if (action != null && token == null) {
	mHandler.removeMessages(MSG_DO_SCHEDULE_DRAW, action);
	}
	}
	}

	private void scheduleAnimationLocked(long now) {
	if (!mAnimationScheduled) {
	mAnimationScheduled = true;
	if (USE_VSYNC) {
	if (DEBUG) {
	Log.d(TAG, "Scheduling vsync for animation.");
	}

	// If running on the Looper thread, then schedule the vsync immediately,
	// otherwise post a message to schedule the vsync from the UI thread
	// as soon as possible.
	if (isRunningOnLooperThreadLocked()) {
	scheduleVsyncLocked();
	} else {
	Message msg = mHandler.obtainMessage(MSG_DO_SCHEDULE_VSYNC);
	msg.setAsynchronous(true);
	mHandler.sendMessageAtFrontOfQueue(msg);
	}
	} else {
	final long nextAnimationTime = Math.max(mLastAnimationTime + sFrameDelay, now);
	if (DEBUG) {
	Log.d(TAG, "Scheduling animation in " + (nextAnimationTime - now) + " ms.");
	}
	Message msg = mHandler.obtainMessage(MSG_DO_ANIMATION);
	msg.setAsynchronous(true);
	mHandler.sendMessageAtTime(msg, nextAnimationTime);
	}
	}
	}

	private void scheduleDrawLocked(long now) {
	if (!mDrawScheduled) {
	mDrawScheduled = true;
	if (USE_ANIMATION_TIMER_FOR_DRAW) {
	scheduleAnimationLocked(now);
	} else {
	if (DEBUG) {
	Log.d(TAG, "Scheduling draw immediately.");
	}
	Message msg = mHandler.obtainMessage(MSG_DO_DRAW);
	msg.setAsynchronous(true);
	mHandler.sendMessageAtTime(msg, now);
	}
	}
	}

	void doAnimation() {
	doAnimationInner();

	if (USE_ANIMATION_TIMER_FOR_DRAW) {
	doDraw();
	}
	}

	void doAnimationInner() {
	final long start;
	Callback callbacks;
	synchronized (mLock) {
	if (!mAnimationScheduled) {
	return; // no work to do
	}
	mAnimationScheduled = false;

	start = SystemClock.uptimeMillis();
	if (DEBUG) {
	Log.d(TAG, "Performing animation: " + Math.max(0, start - mLastAnimationTime)
	+ " ms have elapsed since previous animation.");
	}
	mLastAnimationTime = start;

	callbacks = mAnimationCallbackQueue.extractDueCallbacksLocked(start);
	}

	if (callbacks != null) {
	runCallbacks(callbacks);
	synchronized (mLock) {
	recycleCallbacksLocked(callbacks);
	}
	}

	if (DEBUG) {
	Log.d(TAG, "Animation took " + (SystemClock.uptimeMillis() - start) + " ms.");
	}
	}

	void doDraw() {
	final long start;
	Callback callbacks;
	synchronized (mLock) {
	if (!mDrawScheduled) {
	return; // no work to do
	}
	mDrawScheduled = false;

	start = SystemClock.uptimeMillis();
	if (DEBUG) {
	Log.d(TAG, "Performing draw: " + Math.max(0, start - mLastDrawTime)
	+ " ms have elapsed since previous draw.");
	}
	mLastDrawTime = start;

	callbacks = mDrawCallbackQueue.extractDueCallbacksLocked(start);
	}

	if (callbacks != null) {
	runCallbacks(callbacks);
	synchronized (mLock) {
	recycleCallbacksLocked(callbacks);
	}
	}

	if (DEBUG) {
	Log.d(TAG, "Draw took " + (SystemClock.uptimeMillis() - start) + " ms.");
	}
	}

	void doScheduleVsync() {
	synchronized (mLock) {
	if (mAnimationScheduled) {
	scheduleVsyncLocked();
	}
	}
	}

	void doScheduleAnimation() {
	synchronized (mLock) {
	final long now = SystemClock.uptimeMillis();
	if (mAnimationCallbackQueue.hasDueCallbacksLocked(now)) {
	scheduleAnimationLocked(now);
	}
	}
	}

	void doScheduleDraw() {
	synchronized (mLock) {
	final long now = SystemClock.uptimeMillis();
	if (mDrawCallbackQueue.hasDueCallbacksLocked(now)) {
	scheduleDrawLocked(now);
	}
	}
	}

	private void scheduleVsyncLocked() {
	mDisplayEventReceiver.scheduleVsync();
	}

	private boolean isRunningOnLooperThreadLocked() {
	return Looper.myLooper() == mLooper;
	}

	private void runCallbacks(Callback head) {
	while (head != null) {
	if (DEBUG) {
	Log.d(TAG, "RunCallback: " + head.action + ", token=" + head.token
	+ ", waitMillis=" + (SystemClock.uptimeMillis() - head.dueTime));
	}
	head.action.run();
	head = head.next;
	}
	}

	private void recycleCallbacksLocked(Callback head) {
	while (head != null) {
	final Callback next = head.next;
	recycleCallbackLocked(head);
	head = next;
	}
	}

	private Callback obtainCallbackLocked(long dueTime, Runnable action, Object token) {
	Callback callback = mCallbackPool;
	if (callback == null) {
	callback = new Callback();
	} else {
	mCallbackPool = callback.next;
	callback.next = null;
	}
	callback.dueTime = dueTime;
	callback.action = action;
	callback.token = token;
	return callback;
	}

	private void recycleCallbackLocked(Callback callback) {
	callback.action = null;
	callback.token = null;
	callback.next = mCallbackPool;
	mCallbackPool = callback;
	}

	private final class FrameHandler extends Handler {
	public FrameHandler(Looper looper) {
	super(looper);
	}

	@Override
	public void handleMessage(Message msg) {
	switch (msg.what) {
	case MSG_DO_ANIMATION:
	doAnimation();
	break;
	case MSG_DO_DRAW:
	doDraw();
	break;
	case MSG_DO_SCHEDULE_VSYNC:
	doScheduleVsync();
	break;
	case MSG_DO_SCHEDULE_ANIMATION:
	doScheduleAnimation();
	break;
	case MSG_DO_SCHEDULE_DRAW:
	doScheduleDraw();
	break;
	}
	}
	}

	private final class FrameDisplayEventReceiver extends DisplayEventReceiver {
	public FrameDisplayEventReceiver(Looper looper) {
	super(looper);
	}

	@Override
	public void onVsync(long timestampNanos, int frame) {
	doAnimation();
	}
	}

	private static final class Callback {
	public Callback next;
	public long dueTime;
	public Runnable action;
	public Object token;
	}

	private final class CallbackQueue {
	private Callback mHead;

	public boolean hasDueCallbacksLocked(long now) {
	return mHead != null && mHead.dueTime <= now;
	}

	public Callback extractDueCallbacksLocked(long now) {
	Callback callbacks = mHead;
	if (callbacks == null \|\| callbacks.dueTime > now) {
	return null;
	}

	Callback last = callbacks;
	Callback next = last.next;
	while (next != null) {
	if (next.dueTime > now) {
	last.next = null;
	break;
	}
	last = next;
	next = next.next;
	}
	mHead = next;
	return callbacks;
	}

	public void addCallbackLocked(long dueTime, Runnable action, Object token) {
	Callback callback = obtainCallbackLocked(dueTime, action, token);
	Callback entry = mHead;
	if (entry == null) {
	mHead = callback;
	return;
	}
	if (dueTime < entry.dueTime) {
	callback.next = entry;
	mHead = callback;
	return;
	}
	while (entry.next != null) {
	if (dueTime < entry.next.dueTime) {
	callback.next = entry.next;
	break;
	}
	entry = entry.next;
	}
	entry.next = callback;
	}

	public void removeCallbacksLocked(Runnable action, Object token) {
	Callback predecessor = null;
	for (Callback callback = mHead; callback != null;) {
	final Callback next = callback.next;
	if ((action == null \|\| callback.action == action)
	&& (token == null \|\| callback.token == token)) {
	if (predecessor != null) {
	predecessor.next = next;
	} else {
	mHead = next;
	}
	recycleCallbackLocked(callback);
	} else {
	predecessor = callback;
	}
	callback = next;
	}
	}
	}
	}