1 : /* vim: set shiftwidth=2 tabstop=8 autoindent cindent expandtab: */
2 : /* ***** BEGIN LICENSE BLOCK *****
3 : * Version: MPL 1.1/GPL 2.0/LGPL 2.1
4 : *
5 : * The contents of this file are subject to the Mozilla Public License Version
6 : * 1.1 (the "License"); you may not use this file except in compliance with
7 : * the License. You may obtain a copy of the License at
8 : * http://www.mozilla.org/MPL/
9 : *
10 : * Software distributed under the License is distributed on an "AS IS" basis,
11 : * WITHOUT WARRANTY OF ANY KIND, either express or implied. See the License
12 : * for the specific language governing rights and limitations under the
13 : * License.
14 : *
15 : * The Original Code is nsRefreshDriver.
16 : *
17 : * The Initial Developer of the Original Code is the Mozilla Foundation.
18 : * Portions created by the Initial Developer are Copyright (C) 2009
19 : * the Initial Developer. All Rights Reserved.
20 : *
21 : * Contributor(s):
22 : * L. David Baron <dbaron@dbaron.org>, Mozilla Corporation (original author)
23 : *
24 : * Alternatively, the contents of this file may be used under the terms of
25 : * either the GNU General Public License Version 2 or later (the "GPL"), or
26 : * the GNU Lesser General Public License Version 2.1 or later (the "LGPL"),
27 : * in which case the provisions of the GPL or the LGPL are applicable instead
28 : * of those above. If you wish to allow use of your version of this file only
29 : * under the terms of either the GPL or the LGPL, and not to allow others to
30 : * use your version of this file under the terms of the MPL, indicate your
31 : * decision by deleting the provisions above and replace them with the notice
32 : * and other provisions required by the GPL or the LGPL. If you do not delete
33 : * the provisions above, a recipient may use your version of this file under
34 : * the terms of any one of the MPL, the GPL or the LGPL.
35 : *
36 : * ***** END LICENSE BLOCK ***** */
37 :
38 : /*
39 : * Code to notify things that animate before a refresh, at an appropriate
40 : * refresh rate. (Perhaps temporary, until replaced by compositor.)
41 : */
42 :
43 : #ifndef nsRefreshDriver_h_
44 : #define nsRefreshDriver_h_
45 :
46 : #include "mozilla/TimeStamp.h"
47 : #include "mozFlushType.h"
48 : #include "nsITimer.h"
49 : #include "nsCOMPtr.h"
50 : #include "nsTObserverArray.h"
51 : #include "nsTArray.h"
52 : #include "nsAutoPtr.h"
53 : #include "nsTHashtable.h"
54 : #include "nsHashKeys.h"
55 :
56 : class nsPresContext;
57 : class nsIPresShell;
58 : class nsIDocument;
59 : class imgIRequest;
60 :
61 : /**
62 : * An abstract base class to be implemented by callers wanting to be
63 : * notified at refresh times. When nothing needs to be painted, callers
64 : * may not be notified.
65 : */
66 : class nsARefreshObserver {
67 : public:
68 : // AddRef and Release signatures that match nsISupports. Implementors
69 : // must implement reference counting, and those that do implement
70 : // nsISupports will already have methods with the correct signature.
71 : //
72 : // The refresh driver does NOT hold references to refresh observers
73 : // except while it is notifying them.
74 : NS_IMETHOD_(nsrefcnt) AddRef(void) = 0;
75 : NS_IMETHOD_(nsrefcnt) Release(void) = 0;
76 :
77 : virtual void WillRefresh(mozilla::TimeStamp aTime) = 0;
78 : };
79 :
80 : class nsRefreshDriver : public nsITimerCallback {
81 : public:
82 : nsRefreshDriver(nsPresContext *aPresContext);
83 : ~nsRefreshDriver();
84 :
85 : static void InitializeStatics();
86 :
87 : // nsISupports implementation
88 : NS_DECL_ISUPPORTS
89 :
90 : // nsITimerCallback implementation
91 : NS_DECL_NSITIMERCALLBACK
92 :
93 : /**
94 : * Methods for testing, exposed via nsIDOMWindowUtils. See
95 : * nsIDOMWindowUtils.advanceTimeAndRefresh for description.
96 : */
97 : void AdvanceTimeAndRefresh(PRInt64 aMilliseconds);
98 : void RestoreNormalRefresh();
99 :
100 : /**
101 : * Return the time of the most recent refresh. This is intended to be
102 : * used by callers who want to start an animation now and want to know
103 : * what time to consider the start of the animation. (This helps
104 : * ensure that multiple animations started during the same event off
105 : * the main event loop have the same start time.)
106 : */
107 : mozilla::TimeStamp MostRecentRefresh() const;
108 : /**
109 : * Same thing, but in microseconds since the epoch.
110 : */
111 : PRInt64 MostRecentRefreshEpochTime() const;
112 :
113 : /**
114 : * Add / remove refresh observers. Returns whether the operation
115 : * succeeded.
116 : *
117 : * The flush type affects:
118 : * + the order in which the observers are notified (lowest flush
119 : * type to highest, in order registered)
120 : * + (in the future) which observers are suppressed when the display
121 : * doesn't require current position data or isn't currently
122 : * painting, and, correspondingly, which get notified when there
123 : * is a flush during such suppression
124 : * and it must be either Flush_Style, Flush_Layout, or Flush_Display.
125 : *
126 : * The refresh driver does NOT own a reference to these observers;
127 : * they must remove themselves before they are destroyed.
128 : */
129 : bool AddRefreshObserver(nsARefreshObserver *aObserver,
130 : mozFlushType aFlushType);
131 : bool RemoveRefreshObserver(nsARefreshObserver *aObserver,
132 : mozFlushType aFlushType);
133 :
134 : /**
135 : * Add/Remove imgIRequest versions of observers.
136 : *
137 : * These are used for hooking into the refresh driver for
138 : * controlling animated images.
139 : *
140 : * @note The refresh driver owns a reference to these listeners.
141 : *
142 : * @note Technically, imgIRequest objects are not nsARefreshObservers, but
143 : * for controlling animated image repaint events, we subscribe the
144 : * imgIRequests to the nsRefreshDriver for notification of paint events.
145 : *
146 : * @returns whether the operation succeeded, or void in the case of removal.
147 : */
148 : bool AddImageRequest(imgIRequest* aRequest);
149 : void RemoveImageRequest(imgIRequest* aRequest);
150 : void ClearAllImageRequests();
151 :
152 : /**
153 : * Add / remove presshells that we should flush style and layout on
154 : */
155 : bool AddStyleFlushObserver(nsIPresShell* aShell) {
156 : NS_ASSERTION(!mStyleFlushObservers.Contains(aShell),
157 : "Double-adding style flush observer");
158 : bool appended = mStyleFlushObservers.AppendElement(aShell) != nsnull;
159 : EnsureTimerStarted(false);
160 : return appended;
161 : }
162 : void RemoveStyleFlushObserver(nsIPresShell* aShell) {
163 : mStyleFlushObservers.RemoveElement(aShell);
164 : }
165 : bool AddLayoutFlushObserver(nsIPresShell* aShell) {
166 : NS_ASSERTION(!IsLayoutFlushObserver(aShell),
167 : "Double-adding layout flush observer");
168 : bool appended = mLayoutFlushObservers.AppendElement(aShell) != nsnull;
169 : EnsureTimerStarted(false);
170 : return appended;
171 : }
172 : void RemoveLayoutFlushObserver(nsIPresShell* aShell) {
173 : mLayoutFlushObservers.RemoveElement(aShell);
174 : }
175 : bool IsLayoutFlushObserver(nsIPresShell* aShell) {
176 : return mLayoutFlushObservers.Contains(aShell);
177 : }
178 :
179 : /**
180 : * Remember whether our presshell's view manager needs a flush
181 : */
182 : void ScheduleViewManagerFlush() {
183 : mViewManagerFlushIsPending = true;
184 : EnsureTimerStarted(false);
185 : }
186 : void RevokeViewManagerFlush() {
187 : mViewManagerFlushIsPending = false;
188 : }
189 :
190 : /**
191 : * Add a document for which we have nsIFrameRequestCallbacks
192 : */
193 : void ScheduleFrameRequestCallbacks(nsIDocument* aDocument);
194 :
195 : /**
196 : * Remove a document for which we have nsIFrameRequestCallbacks
197 : */
198 : void RevokeFrameRequestCallbacks(nsIDocument* aDocument);
199 :
200 : /**
201 : * Tell the refresh driver that it is done driving refreshes and
202 : * should stop its timer and forget about its pres context. This may
203 : * be called from within a refresh.
204 : */
205 : void Disconnect() {
206 : StopTimer();
207 : mPresContext = nsnull;
208 : }
209 :
210 : /**
211 : * Freeze the refresh driver. It should stop delivering future
212 : * refreshes until thawed.
213 : */
214 : void Freeze();
215 :
216 : /**
217 : * Thaw the refresh driver. If needed, it should start delivering
218 : * refreshes again.
219 : */
220 : void Thaw();
221 :
222 : /**
223 : * Throttle or unthrottle the refresh driver. This is done if the
224 : * corresponding presshell is hidden or shown.
225 : */
226 : void SetThrottled(bool aThrottled);
227 :
228 : /**
229 : * Return the prescontext we were initialized with
230 : */
231 : nsPresContext* PresContext() const { return mPresContext; }
232 :
233 : #ifdef DEBUG
234 : /**
235 : * Check whether the given observer is an observer for the given flush type
236 : */
237 : bool IsRefreshObserver(nsARefreshObserver *aObserver,
238 : mozFlushType aFlushType);
239 : #endif
240 :
241 : /**
242 : * Default interval the refresh driver uses, in ms.
243 : */
244 : static PRInt32 DefaultInterval();
245 :
246 : private:
247 : typedef nsTObserverArray<nsARefreshObserver*> ObserverArray;
248 : typedef nsTHashtable<nsISupportsHashKey> RequestTable;
249 :
250 : void EnsureTimerStarted(bool aAdjustingTimer);
251 : void StopTimer();
252 :
253 : PRUint32 ObserverCount() const;
254 : PRUint32 ImageRequestCount() const;
255 : static PLDHashOperator ImageRequestEnumerator(nsISupportsHashKey* aEntry,
256 : void* aUserArg);
257 : void UpdateMostRecentRefresh();
258 : ObserverArray& ArrayFor(mozFlushType aFlushType);
259 : // Trigger a refresh immediately, if haven't been disconnected or frozen.
260 : void DoRefresh();
261 :
262 : PRInt32 GetRefreshTimerInterval() const;
263 : PRInt32 GetRefreshTimerType() const;
264 :
265 0 : bool HaveFrameRequestCallbacks() const {
266 0 : return mFrameRequestCallbackDocs.Length() != 0;
267 : }
268 :
269 : nsCOMPtr<nsITimer> mTimer;
270 : mozilla::TimeStamp mMostRecentRefresh; // only valid when mTimer non-null
271 : PRInt64 mMostRecentRefreshEpochTime; // same thing as mMostRecentRefresh,
272 : // but in microseconds since the epoch.
273 :
274 : nsPresContext *mPresContext; // weak; pres context passed in constructor
275 : // and unset in Disconnect
276 :
277 : bool mFrozen;
278 : bool mThrottled;
279 : bool mTestControllingRefreshes;
280 : /* If mTimer is non-null, this boolean indicates whether the timer is
281 : a precise timer. If mTimer is null, this boolean's value can be
282 : anything. */
283 : bool mTimerIsPrecise;
284 : bool mViewManagerFlushIsPending;
285 :
286 : // separate arrays for each flush type we support
287 : ObserverArray mObservers[3];
288 : RequestTable mRequests;
289 :
290 : nsAutoTArray<nsIPresShell*, 16> mStyleFlushObservers;
291 : nsAutoTArray<nsIPresShell*, 16> mLayoutFlushObservers;
292 : // nsTArray on purpose, because we want to be able to swap.
293 : nsTArray<nsIDocument*> mFrameRequestCallbackDocs;
294 :
295 : // This is the last interval we used for our timer. May be 0 if we
296 : // haven't computed a timer interval yet.
297 : mutable PRInt32 mLastTimerInterval;
298 :
299 : // Helper struct for processing image requests
300 : struct ImageRequestParameters {
301 : mozilla::TimeStamp ts;
302 : };
303 : };
304 :
305 : #endif /* !defined(nsRefreshDriver_h_) */
|