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