DispSync.h revision c751e92c56de5f335a36e68607c7a6c627dcd0dc
1faf77cce9d9ec0238d6999b3bd0d40c71ff403c5Jamie Gennis/* 2faf77cce9d9ec0238d6999b3bd0d40c71ff403c5Jamie Gennis * Copyright (C) 2012 The Android Open Source Project 3faf77cce9d9ec0238d6999b3bd0d40c71ff403c5Jamie Gennis * 4faf77cce9d9ec0238d6999b3bd0d40c71ff403c5Jamie Gennis * Licensed under the Apache License, Version 2.0 (the "License"); 5faf77cce9d9ec0238d6999b3bd0d40c71ff403c5Jamie Gennis * you may not use this file except in compliance with the License. 6faf77cce9d9ec0238d6999b3bd0d40c71ff403c5Jamie Gennis * You may obtain a copy of the License at 7faf77cce9d9ec0238d6999b3bd0d40c71ff403c5Jamie Gennis * 8faf77cce9d9ec0238d6999b3bd0d40c71ff403c5Jamie Gennis * http://www.apache.org/licenses/LICENSE-2.0 9faf77cce9d9ec0238d6999b3bd0d40c71ff403c5Jamie Gennis * 10faf77cce9d9ec0238d6999b3bd0d40c71ff403c5Jamie Gennis * Unless required by applicable law or agreed to in writing, software 11faf77cce9d9ec0238d6999b3bd0d40c71ff403c5Jamie Gennis * distributed under the License is distributed on an "AS IS" BASIS, 12faf77cce9d9ec0238d6999b3bd0d40c71ff403c5Jamie Gennis * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 13faf77cce9d9ec0238d6999b3bd0d40c71ff403c5Jamie Gennis * See the License for the specific language governing permissions and 14faf77cce9d9ec0238d6999b3bd0d40c71ff403c5Jamie Gennis * limitations under the License. 15faf77cce9d9ec0238d6999b3bd0d40c71ff403c5Jamie Gennis */ 16faf77cce9d9ec0238d6999b3bd0d40c71ff403c5Jamie Gennis 17faf77cce9d9ec0238d6999b3bd0d40c71ff403c5Jamie Gennis#ifndef ANDROID_DISPSYNC_H 18faf77cce9d9ec0238d6999b3bd0d40c71ff403c5Jamie Gennis#define ANDROID_DISPSYNC_H 19faf77cce9d9ec0238d6999b3bd0d40c71ff403c5Jamie Gennis 20faf77cce9d9ec0238d6999b3bd0d40c71ff403c5Jamie Gennis#include <stddef.h> 21faf77cce9d9ec0238d6999b3bd0d40c71ff403c5Jamie Gennis 22faf77cce9d9ec0238d6999b3bd0d40c71ff403c5Jamie Gennis#include <utils/Mutex.h> 23faf77cce9d9ec0238d6999b3bd0d40c71ff403c5Jamie Gennis#include <utils/Timers.h> 24faf77cce9d9ec0238d6999b3bd0d40c71ff403c5Jamie Gennis#include <utils/RefBase.h> 25faf77cce9d9ec0238d6999b3bd0d40c71ff403c5Jamie Gennis 26faf77cce9d9ec0238d6999b3bd0d40c71ff403c5Jamie Gennisnamespace android { 27faf77cce9d9ec0238d6999b3bd0d40c71ff403c5Jamie Gennis 28faf77cce9d9ec0238d6999b3bd0d40c71ff403c5Jamie Gennisclass String8; 29faf77cce9d9ec0238d6999b3bd0d40c71ff403c5Jamie Gennisclass Fence; 30faf77cce9d9ec0238d6999b3bd0d40c71ff403c5Jamie Gennisclass DispSyncThread; 31faf77cce9d9ec0238d6999b3bd0d40c71ff403c5Jamie Gennis 32faf77cce9d9ec0238d6999b3bd0d40c71ff403c5Jamie Gennis// DispSync maintains a model of the periodic hardware-based vsync events of a 33faf77cce9d9ec0238d6999b3bd0d40c71ff403c5Jamie Gennis// display and uses that model to execute period callbacks at specific phase 34faf77cce9d9ec0238d6999b3bd0d40c71ff403c5Jamie Gennis// offsets from the hardware vsync events. The model is constructed by 35faf77cce9d9ec0238d6999b3bd0d40c71ff403c5Jamie Gennis// feeding consecutive hardware event timestamps to the DispSync object via 36faf77cce9d9ec0238d6999b3bd0d40c71ff403c5Jamie Gennis// the addResyncSample method. 37faf77cce9d9ec0238d6999b3bd0d40c71ff403c5Jamie Gennis// 38faf77cce9d9ec0238d6999b3bd0d40c71ff403c5Jamie Gennis// The model is validated using timestamps from Fence objects that are passed 39faf77cce9d9ec0238d6999b3bd0d40c71ff403c5Jamie Gennis// to the DispSync object via the addPresentFence method. These fence 40faf77cce9d9ec0238d6999b3bd0d40c71ff403c5Jamie Gennis// timestamps should correspond to a hardware vsync event, but they need not 41faf77cce9d9ec0238d6999b3bd0d40c71ff403c5Jamie Gennis// be consecutive hardware vsync times. If this method determines that the 42faf77cce9d9ec0238d6999b3bd0d40c71ff403c5Jamie Gennis// current model accurately represents the hardware event times it will return 43faf77cce9d9ec0238d6999b3bd0d40c71ff403c5Jamie Gennis// false to indicate that a resynchronization (via addResyncSample) is not 44faf77cce9d9ec0238d6999b3bd0d40c71ff403c5Jamie Gennis// needed. 45faf77cce9d9ec0238d6999b3bd0d40c71ff403c5Jamie Gennisclass DispSync { 46faf77cce9d9ec0238d6999b3bd0d40c71ff403c5Jamie Gennis 47faf77cce9d9ec0238d6999b3bd0d40c71ff403c5Jamie Gennispublic: 48faf77cce9d9ec0238d6999b3bd0d40c71ff403c5Jamie Gennis 49faf77cce9d9ec0238d6999b3bd0d40c71ff403c5Jamie Gennis class Callback: public virtual RefBase { 50faf77cce9d9ec0238d6999b3bd0d40c71ff403c5Jamie Gennis public: 51faf77cce9d9ec0238d6999b3bd0d40c71ff403c5Jamie Gennis virtual ~Callback() {}; 52faf77cce9d9ec0238d6999b3bd0d40c71ff403c5Jamie Gennis virtual void onDispSyncEvent(nsecs_t when) = 0; 53faf77cce9d9ec0238d6999b3bd0d40c71ff403c5Jamie Gennis }; 54faf77cce9d9ec0238d6999b3bd0d40c71ff403c5Jamie Gennis 55faf77cce9d9ec0238d6999b3bd0d40c71ff403c5Jamie Gennis DispSync(); 56faf77cce9d9ec0238d6999b3bd0d40c71ff403c5Jamie Gennis ~DispSync(); 57faf77cce9d9ec0238d6999b3bd0d40c71ff403c5Jamie Gennis 58faf77cce9d9ec0238d6999b3bd0d40c71ff403c5Jamie Gennis void reset(); 59faf77cce9d9ec0238d6999b3bd0d40c71ff403c5Jamie Gennis 60faf77cce9d9ec0238d6999b3bd0d40c71ff403c5Jamie Gennis // addPresentFence adds a fence for use in validating the current vsync 61faf77cce9d9ec0238d6999b3bd0d40c71ff403c5Jamie Gennis // event model. The fence need not be signaled at the time 62faf77cce9d9ec0238d6999b3bd0d40c71ff403c5Jamie Gennis // addPresentFence is called. When the fence does signal, its timestamp 63faf77cce9d9ec0238d6999b3bd0d40c71ff403c5Jamie Gennis // should correspond to a hardware vsync event. Unlike the 64faf77cce9d9ec0238d6999b3bd0d40c71ff403c5Jamie Gennis // addResyncSample method, the timestamps of consecutive fences need not 65faf77cce9d9ec0238d6999b3bd0d40c71ff403c5Jamie Gennis // correspond to consecutive hardware vsync events. 66faf77cce9d9ec0238d6999b3bd0d40c71ff403c5Jamie Gennis // 67faf77cce9d9ec0238d6999b3bd0d40c71ff403c5Jamie Gennis // This method should be called with the retire fence from each HWComposer 68faf77cce9d9ec0238d6999b3bd0d40c71ff403c5Jamie Gennis // set call that affects the display. 69faf77cce9d9ec0238d6999b3bd0d40c71ff403c5Jamie Gennis bool addPresentFence(const sp<Fence>& fence); 70faf77cce9d9ec0238d6999b3bd0d40c71ff403c5Jamie Gennis 71faf77cce9d9ec0238d6999b3bd0d40c71ff403c5Jamie Gennis // The beginResync, addResyncSample, and endResync methods are used to re- 72faf77cce9d9ec0238d6999b3bd0d40c71ff403c5Jamie Gennis // synchronize the DispSync's model to the hardware vsync events. The re- 73faf77cce9d9ec0238d6999b3bd0d40c71ff403c5Jamie Gennis // synchronization process involves first calling beginResync, then 74faf77cce9d9ec0238d6999b3bd0d40c71ff403c5Jamie Gennis // calling addResyncSample with a sequence of consecutive hardware vsync 75faf77cce9d9ec0238d6999b3bd0d40c71ff403c5Jamie Gennis // event timestamps, and finally calling endResync when addResyncSample 76faf77cce9d9ec0238d6999b3bd0d40c71ff403c5Jamie Gennis // indicates that no more samples are needed by returning false. 77faf77cce9d9ec0238d6999b3bd0d40c71ff403c5Jamie Gennis // 78faf77cce9d9ec0238d6999b3bd0d40c71ff403c5Jamie Gennis // This resynchronization process should be performed whenever the display 79faf77cce9d9ec0238d6999b3bd0d40c71ff403c5Jamie Gennis // is turned on (i.e. once immediately after it's turned on) and whenever 80faf77cce9d9ec0238d6999b3bd0d40c71ff403c5Jamie Gennis // addPresentFence returns true indicating that the model has drifted away 81faf77cce9d9ec0238d6999b3bd0d40c71ff403c5Jamie Gennis // from the hardware vsync events. 82faf77cce9d9ec0238d6999b3bd0d40c71ff403c5Jamie Gennis void beginResync(); 83faf77cce9d9ec0238d6999b3bd0d40c71ff403c5Jamie Gennis bool addResyncSample(nsecs_t timestamp); 84faf77cce9d9ec0238d6999b3bd0d40c71ff403c5Jamie Gennis void endResync(); 85faf77cce9d9ec0238d6999b3bd0d40c71ff403c5Jamie Gennis 8641d67d7ab4da1c393497a620a116a854b3c618e7Andy McFadden // The setPeriod method sets the vsync event model's period to a specific 87faf77cce9d9ec0238d6999b3bd0d40c71ff403c5Jamie Gennis // value. This should be used to prime the model when a display is first 88faf77cce9d9ec0238d6999b3bd0d40c71ff403c5Jamie Gennis // turned on. It should NOT be used after that. 89faf77cce9d9ec0238d6999b3bd0d40c71ff403c5Jamie Gennis void setPeriod(nsecs_t period); 90faf77cce9d9ec0238d6999b3bd0d40c71ff403c5Jamie Gennis 91f52b3c88f18c0546526996c839fbce74172e11c7Ruchi Kandoi // Setting the low power mode reduces the frame rate to half of the default 92f52b3c88f18c0546526996c839fbce74172e11c7Ruchi Kandoi void setLowPowerMode(bool enabled); 93f52b3c88f18c0546526996c839fbce74172e11c7Ruchi Kandoi 94faf77cce9d9ec0238d6999b3bd0d40c71ff403c5Jamie Gennis // addEventListener registers a callback to be called repeatedly at the 95faf77cce9d9ec0238d6999b3bd0d40c71ff403c5Jamie Gennis // given phase offset from the hardware vsync events. The callback is 96faf77cce9d9ec0238d6999b3bd0d40c71ff403c5Jamie Gennis // called from a separate thread and it should return reasonably quickly 97faf77cce9d9ec0238d6999b3bd0d40c71ff403c5Jamie Gennis // (i.e. within a few hundred microseconds). 98faf77cce9d9ec0238d6999b3bd0d40c71ff403c5Jamie Gennis status_t addEventListener(nsecs_t phase, const sp<Callback>& callback); 99faf77cce9d9ec0238d6999b3bd0d40c71ff403c5Jamie Gennis 100faf77cce9d9ec0238d6999b3bd0d40c71ff403c5Jamie Gennis // removeEventListener removes an already-registered event callback. Once 101faf77cce9d9ec0238d6999b3bd0d40c71ff403c5Jamie Gennis // this method returns that callback will no longer be called by the 102faf77cce9d9ec0238d6999b3bd0d40c71ff403c5Jamie Gennis // DispSync object. 103faf77cce9d9ec0238d6999b3bd0d40c71ff403c5Jamie Gennis status_t removeEventListener(const sp<Callback>& callback); 104faf77cce9d9ec0238d6999b3bd0d40c71ff403c5Jamie Gennis 10541d67d7ab4da1c393497a620a116a854b3c618e7Andy McFadden // computeNextRefresh computes when the next refresh is expected to begin. 10641d67d7ab4da1c393497a620a116a854b3c618e7Andy McFadden // The periodOffset value can be used to move forward or backward; an 10741d67d7ab4da1c393497a620a116a854b3c618e7Andy McFadden // offset of zero is the next refresh, -1 is the previous refresh, 1 is 10841d67d7ab4da1c393497a620a116a854b3c618e7Andy McFadden // the refresh after next. etc. 10941d67d7ab4da1c393497a620a116a854b3c618e7Andy McFadden nsecs_t computeNextRefresh(int periodOffset) const; 11041d67d7ab4da1c393497a620a116a854b3c618e7Andy McFadden 111c751e92c56de5f335a36e68607c7a6c627dcd0dcAndy McFadden // dump appends human-readable debug info to the result string. 112c751e92c56de5f335a36e68607c7a6c627dcd0dcAndy McFadden void dump(String8& result) const; 113c751e92c56de5f335a36e68607c7a6c627dcd0dcAndy McFadden 114faf77cce9d9ec0238d6999b3bd0d40c71ff403c5Jamie Gennisprivate: 115faf77cce9d9ec0238d6999b3bd0d40c71ff403c5Jamie Gennis 116faf77cce9d9ec0238d6999b3bd0d40c71ff403c5Jamie Gennis void updateModelLocked(); 117faf77cce9d9ec0238d6999b3bd0d40c71ff403c5Jamie Gennis void updateErrorLocked(); 118faf77cce9d9ec0238d6999b3bd0d40c71ff403c5Jamie Gennis void resetErrorLocked(); 119faf77cce9d9ec0238d6999b3bd0d40c71ff403c5Jamie Gennis 120faf77cce9d9ec0238d6999b3bd0d40c71ff403c5Jamie Gennis enum { MAX_RESYNC_SAMPLES = 32 }; 121faf77cce9d9ec0238d6999b3bd0d40c71ff403c5Jamie Gennis enum { MIN_RESYNC_SAMPLES_FOR_UPDATE = 3 }; 122faf77cce9d9ec0238d6999b3bd0d40c71ff403c5Jamie Gennis enum { NUM_PRESENT_SAMPLES = 8 }; 123faf77cce9d9ec0238d6999b3bd0d40c71ff403c5Jamie Gennis enum { MAX_RESYNC_SAMPLES_WITHOUT_PRESENT = 12 }; 124faf77cce9d9ec0238d6999b3bd0d40c71ff403c5Jamie Gennis 125faf77cce9d9ec0238d6999b3bd0d40c71ff403c5Jamie Gennis // mPeriod is the computed period of the modeled vsync events in 126faf77cce9d9ec0238d6999b3bd0d40c71ff403c5Jamie Gennis // nanoseconds. 127faf77cce9d9ec0238d6999b3bd0d40c71ff403c5Jamie Gennis nsecs_t mPeriod; 128faf77cce9d9ec0238d6999b3bd0d40c71ff403c5Jamie Gennis 129faf77cce9d9ec0238d6999b3bd0d40c71ff403c5Jamie Gennis // mPhase is the phase offset of the modeled vsync events. It is the 130faf77cce9d9ec0238d6999b3bd0d40c71ff403c5Jamie Gennis // number of nanoseconds from time 0 to the first vsync event. 131faf77cce9d9ec0238d6999b3bd0d40c71ff403c5Jamie Gennis nsecs_t mPhase; 132faf77cce9d9ec0238d6999b3bd0d40c71ff403c5Jamie Gennis 133faf77cce9d9ec0238d6999b3bd0d40c71ff403c5Jamie Gennis // mError is the computed model error. It is based on the difference 134faf77cce9d9ec0238d6999b3bd0d40c71ff403c5Jamie Gennis // between the estimated vsync event times and those observed in the 135faf77cce9d9ec0238d6999b3bd0d40c71ff403c5Jamie Gennis // mPresentTimes array. 136faf77cce9d9ec0238d6999b3bd0d40c71ff403c5Jamie Gennis nsecs_t mError; 137faf77cce9d9ec0238d6999b3bd0d40c71ff403c5Jamie Gennis 138faf77cce9d9ec0238d6999b3bd0d40c71ff403c5Jamie Gennis // These member variables are the state used during the resynchronization 139faf77cce9d9ec0238d6999b3bd0d40c71ff403c5Jamie Gennis // process to store information about the hardware vsync event times used 140faf77cce9d9ec0238d6999b3bd0d40c71ff403c5Jamie Gennis // to compute the model. 141faf77cce9d9ec0238d6999b3bd0d40c71ff403c5Jamie Gennis nsecs_t mResyncSamples[MAX_RESYNC_SAMPLES]; 142faf77cce9d9ec0238d6999b3bd0d40c71ff403c5Jamie Gennis size_t mFirstResyncSample; 143faf77cce9d9ec0238d6999b3bd0d40c71ff403c5Jamie Gennis size_t mNumResyncSamples; 144faf77cce9d9ec0238d6999b3bd0d40c71ff403c5Jamie Gennis int mNumResyncSamplesSincePresent; 145faf77cce9d9ec0238d6999b3bd0d40c71ff403c5Jamie Gennis 146faf77cce9d9ec0238d6999b3bd0d40c71ff403c5Jamie Gennis // These member variables store information about the present fences used 147faf77cce9d9ec0238d6999b3bd0d40c71ff403c5Jamie Gennis // to validate the currently computed model. 148faf77cce9d9ec0238d6999b3bd0d40c71ff403c5Jamie Gennis sp<Fence> mPresentFences[NUM_PRESENT_SAMPLES]; 149faf77cce9d9ec0238d6999b3bd0d40c71ff403c5Jamie Gennis nsecs_t mPresentTimes[NUM_PRESENT_SAMPLES]; 150faf77cce9d9ec0238d6999b3bd0d40c71ff403c5Jamie Gennis size_t mPresentSampleOffset; 151faf77cce9d9ec0238d6999b3bd0d40c71ff403c5Jamie Gennis 152faf77cce9d9ec0238d6999b3bd0d40c71ff403c5Jamie Gennis // mThread is the thread from which all the callbacks are called. 153faf77cce9d9ec0238d6999b3bd0d40c71ff403c5Jamie Gennis sp<DispSyncThread> mThread; 154faf77cce9d9ec0238d6999b3bd0d40c71ff403c5Jamie Gennis 155faf77cce9d9ec0238d6999b3bd0d40c71ff403c5Jamie Gennis // mMutex is used to protect access to all member variables. 156faf77cce9d9ec0238d6999b3bd0d40c71ff403c5Jamie Gennis mutable Mutex mMutex; 157faf77cce9d9ec0238d6999b3bd0d40c71ff403c5Jamie Gennis}; 158faf77cce9d9ec0238d6999b3bd0d40c71ff403c5Jamie Gennis 159faf77cce9d9ec0238d6999b3bd0d40c71ff403c5Jamie Gennis} 160faf77cce9d9ec0238d6999b3bd0d40c71ff403c5Jamie Gennis 161faf77cce9d9ec0238d6999b3bd0d40c71ff403c5Jamie Gennis#endif // ANDROID_DISPSYNC_H 162