Debian Codegraph @

closure-library/closure/goog/dom/animationframe/animationframe.js

raw
1 // Copyright 2014 The Closure Library Authors. All Rights Reserved.
2 //
3 // Licensed under the Apache License, Version 2.0 (the "License");
4 // you may not use this file except in compliance with the License.
5 // You may obtain a copy of the License at
6 //
7 // http://www.apache.org/licenses/LICENSE-2.0
8 //
9 // Unless required by applicable law or agreed to in writing, software
10 // distributed under the License is distributed on an "AS-IS" BASIS,
11 // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12 // See the License for the specific language governing permissions and
13 // limitations under the License.
14
15 /**
16 * @fileoverview goog.dom.animationFrame permits work to be done in-sync with
17 * the render refresh rate of the browser and to divide work up globally based
18 * on whether the intent is to measure or to mutate the DOM. The latter avoids
19 * repeated style recalculation which can be really slow.
20 *
21 * Goals of the API:
22 * <ul>
23 * <li>Make it easy to schedule work for the next animation frame.
24 * <li>Make it easy to only do work once per animation frame, even if two
25 * events fire that trigger the same work.
26 * <li>Make it easy to do all work in two phases to avoid repeated style
27 * recalculation caused by interleaved reads and writes.
28 * <li>Avoid creating closures per schedule operation.
29 * </ul>
30 *
31 *
32 * Programmatic:
33 * <pre>
34 * let animationTask = goog.dom.animationFrame.createTask(
35 * {
36 * measure: function(state) {
37 * state.width = goog.style.getSize(elem).width;
38 * this.animationTask();
39 * },
40 * mutate: function(state) {
41 * goog.style.setWidth(elem, Math.floor(state.width / 2));
42 * },
43 * },
44 * this);
45 * </pre>
46 *
47 * See also
48 * https://developer.mozilla.org/en-US/docs/Web/API/window.requestAnimationFrame
49 */
50
51 goog.provide('goog.dom.animationFrame');
52 goog.provide('goog.dom.animationFrame.Spec');
53 goog.provide('goog.dom.animationFrame.State');
54
55 goog.require('goog.dom.animationFrame.polyfill');
56
57 // Install the polyfill.
58 goog.dom.animationFrame.polyfill.install();
59
60
61 /**
62 * @typedef {{
63 * id: number,
64 * fn: !Function,
65 * context: (!Object|undefined)
66 * }}
67 * @private
68 */
69 goog.dom.animationFrame.Task_;
70
71
72 /**
73 * @typedef {{
74 * measureTask: goog.dom.animationFrame.Task_,
75 * mutateTask: goog.dom.animationFrame.Task_,
76 * state: (!Object|undefined),
77 * args: (!Array|undefined),
78 * isScheduled: boolean
79 * }}
80 * @private
81 */
82 goog.dom.animationFrame.TaskSet_;
83
84
85 /**
86 * @typedef {{
87 * measure: (!Function|undefined),
88 * mutate: (!Function|undefined)
89 * }}
90 */
91 goog.dom.animationFrame.Spec;
92
93
94
95 /**
96 * A type to represent state. Users may add properties as desired.
97 * @constructor
98 * @final
99 */
100 goog.dom.animationFrame.State = function() {};
101
102
103 /**
104 * Saves a set of tasks to be executed in the next requestAnimationFrame phase.
105 * This list is initialized once before any event firing occurs. It is not
106 * affected by the fired events or the requestAnimationFrame processing (unless
107 * a new event is created during the processing).
108 * @private {!Array<!Array<goog.dom.animationFrame.TaskSet_>>}
109 */
110 goog.dom.animationFrame.tasks_ = [[], []];
111
112
113 /**
114 * Values are 0 or 1, for whether the first or second array should be used to
115 * lookup or add tasks.
116 * @private {number}
117 */
118 goog.dom.animationFrame.doubleBufferIndex_ = 0;
119
120
121 /**
122 * Whether we have already requested an animation frame that hasn't happened
123 * yet.
124 * @private {boolean}
125 */
126 goog.dom.animationFrame.requestedFrame_ = false;
127
128
129 /**
130 * Counter to generate IDs for tasks.
131 * @private {number}
132 */
133 goog.dom.animationFrame.taskId_ = 0;
134
135
136 /**
137 * Whether the animationframe runTasks_ loop is currently running.
138 * @private {boolean}
139 */
140 goog.dom.animationFrame.running_ = false;
141
142
143 /**
144 * Returns a function that schedules the two passed-in functions to be run upon
145 * the next animation frame. Calling the function again during the same
146 * animation frame does nothing.
147 *
148 * The function under the "measure" key will run first and together with all
149 * other functions scheduled under this key and the function under "mutate" will
150 * run after that.
151 *
152 * @param {{
153 * measure: (function(this:THIS, !goog.dom.animationFrame.State)|undefined),
154 * mutate: (function(this:THIS, !goog.dom.animationFrame.State)|undefined)
155 * }} spec
156 * @param {THIS=} opt_context Context in which to run the function.
157 * @return {function(...?)}
158 * @template THIS
159 */
160 goog.dom.animationFrame.createTask = function(spec, opt_context) {
161 var id = goog.dom.animationFrame.taskId_++;
162 var measureTask = {id: id, fn: spec.measure, context: opt_context};
163 var mutateTask = {id: id, fn: spec.mutate, context: opt_context};
164
165 var taskSet = {
166 measureTask: measureTask,
167 mutateTask: mutateTask,
168 state: {},
169 args: undefined,
170 isScheduled: false
171 };
172
173 return function() {
174 // Save args and state.
175 if (arguments.length > 0) {
176 // The state argument goes last. That is kinda horrible but compatible
177 // with {@see wiz.async.method}.
178 if (!taskSet.args) {
179 taskSet.args = [];
180 }
181 taskSet.args.length = 0;
182 taskSet.args.push.apply(taskSet.args, arguments);
183 taskSet.args.push(taskSet.state);
184 } else {
185 if (!taskSet.args || taskSet.args.length == 0) {
186 taskSet.args = [taskSet.state];
187 } else {
188 taskSet.args[0] = taskSet.state;
189 taskSet.args.length = 1;
190 }
191 }
192 if (!taskSet.isScheduled) {
193 taskSet.isScheduled = true;
194 var tasksArray = goog.dom.animationFrame
195 .tasks_[goog.dom.animationFrame.doubleBufferIndex_];
196 tasksArray.push(
197 /** @type {goog.dom.animationFrame.TaskSet_} */ (taskSet));
198 }
199 goog.dom.animationFrame.requestAnimationFrame_();
200 };
201 };
202
203
204 /**
205 * Run scheduled tasks.
206 * @private
207 */
208 goog.dom.animationFrame.runTasks_ = function() {
209 goog.dom.animationFrame.running_ = true;
210 goog.dom.animationFrame.requestedFrame_ = false;
211 var tasksArray = goog.dom.animationFrame
212 .tasks_[goog.dom.animationFrame.doubleBufferIndex_];
213 var taskLength = tasksArray.length;
214
215 // During the runTasks_, if there is a recursive call to queue up more
216 // task(s) for the next frame, we use double-buffering for that.
217 goog.dom.animationFrame.doubleBufferIndex_ =
218 (goog.dom.animationFrame.doubleBufferIndex_ + 1) % 2;
219
220 var task;
221
222 // Run all the measure tasks first.
223 for (var i = 0; i < taskLength; ++i) {
224 task = tasksArray[i];
225 var measureTask = task.measureTask;
226 task.isScheduled = false;
227 if (measureTask.fn) {
228 // TODO (perumaal): Handle any exceptions thrown by the lambda.
229 measureTask.fn.apply(measureTask.context, task.args);
230 }
231 }
232
233 // Run the mutate tasks next.
234 for (var i = 0; i < taskLength; ++i) {
235 task = tasksArray[i];
236 var mutateTask = task.mutateTask;
237 task.isScheduled = false;
238 if (mutateTask.fn) {
239 // TODO (perumaal): Handle any exceptions thrown by the lambda.
240 mutateTask.fn.apply(mutateTask.context, task.args);
241 }
242
243 // Clear state for next vsync.
244 task.state = {};
245 }
246
247 // Clear the tasks array as we have finished processing all the tasks.
248 tasksArray.length = 0;
249 goog.dom.animationFrame.running_ = false;
250 };
251
252
253 /**
254 * @return {boolean} Whether the animationframe is currently running. For use
255 * by callers who need not to delay tasks scheduled during runTasks_ for an
256 * additional frame.
257 */
258 goog.dom.animationFrame.isRunning = function() {
259 return goog.dom.animationFrame.running_;
260 };
261
262
263 /**
264 * Request {@see goog.dom.animationFrame.runTasks_} to be called upon the
265 * next animation frame if we haven't done so already.
266 * @private
267 */
268 goog.dom.animationFrame.requestAnimationFrame_ = function() {
269 if (goog.dom.animationFrame.requestedFrame_) {
270 return;
271 }
272 goog.dom.animationFrame.requestedFrame_ = true;
273 window.requestAnimationFrame(goog.dom.animationFrame.runTasks_);
274 };