core/java/android/view/Choreographer.java

/*
 * 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;
            }
        }
    }
}