­ ­ ­ ­ ­ ­ ­ ­ ­ ­ ­ ­ ­ ­ ­ ­ ­ ­ import { Observable } from '../../Observable'; import { Subscription } from '../../Subscription'; import { TimestampProvider } from "../../types"; import { performanceTimestampProvider } from '../../scheduler/performanceTimestampProvider'; import { animationFrameProvider } from '../../scheduler/animationFrameProvider'; /** * An observable of animation frames * * Emits the the amount of time elapsed since subscription and the timestamp on each animation frame. * Defaults to milliseconds provided to the requestAnimationFrame's callback. Does not end on its own. * * Every subscription will start a separate animation loop. Since animation frames are always scheduled * by the browser to occur directly before a repaint, scheduling more than one animation frame synchronously * should not be much different or have more overhead than looping over an array of events during * a single animation frame. However, if for some reason the developer would like to ensure the * execution of animation-related handlers are all executed during the same task by the engine, * the `share` operator can be used. * * This is useful for setting up animations with RxJS. * * ### Example * * Tweening a div to move it on the screen * * ```ts * import { animationFrames } from 'rxjs'; * import { map, takeWhile, endWith } from 'rxjs/operators'; * * function tween(start: number, end: number, duration: number) { * const diff = end - start; * return animationFrames().pipe( * // Figure out what percentage of time has passed * map(({elapsed}) => elapsed / duration), * // Take the vector while less than 100% * takeWhile(v => v < 1), * // Finish with 100% * endWith(1), * // Calculate the distance traveled between start and end * map(v => v * diff + start) * ); * } * * // Setup a div for us to move around * const div = document.createElement('div'); * document.body.appendChild(div); * div.style.position = 'absolute'; * div.style.width = '40px'; * div.style.height = '40px'; * div.style.backgroundColor = 'lime'; * div.style.transform = 'translate3d(10px, 0, 0)'; * * tween(10, 200, 4000).subscribe(x => { * div.style.transform = `translate3d(${x}px, 0, 0)`; * }); * ``` * * ### Example * * Providing a custom timestamp provider * * ```ts * import { animationFrames, TimestampProvider } from 'rxjs'; * * // A custom timestamp provider * let now = 0; * const customTSProvider: TimestampProvider = { * now() { return now++; } * }; * * const source$ = animationFrames(customTSProvider); * * // Log increasing numbers 0...1...2... on every animation frame. * source$.subscribe(({ elapsed }) => console.log(elapsed)); * ``` * * @param timestampProvider An object with a `now` method that provides a numeric timestamp */ export function animationFrames(timestampProvider?: TimestampProvider) { return timestampProvider ? animationFramesFactory(timestampProvider) : DEFAULT_ANIMATION_FRAMES; } /** * Does the work of creating the observable for `animationFrames`. * @param timestampProvider The timestamp provider to use to create the observable */ function animationFramesFactory(timestampProvider?: TimestampProvider) { const { schedule } = animationFrameProvider; return new Observable<{ timestamp: number, elapsed: number }>(subscriber => { const subscription = new Subscription(); // If no timestamp provider is specified, use performance.now() - as it // will return timestamps 'compatible' with those passed to the run // callback and won't be affected by NTP adjustments, etc. const provider = timestampProvider || performanceTimestampProvider; // Capture the start time upon subscription, as the run callback can remain // queued for a considerable period of time and the elapsed time should // represent the time elapsed since subscription - not the time since the // first rendered animation frame. const start = provider.now(); const run = (timestamp: DOMHighResTimeStamp | number) => { // Use the provider's timestamp to calculate the elapsed time. Note that // this means - if the caller hasn't passed a provider - that // performance.now() will be used instead of the timestamp that was // passed to the run callback. The reason for this is that the timestamp // passed to the callback can be earlier than the start time, as it // represents the time at which the browser decided it would render any // queued frames - and that time can be earlier the captured start time. const now = provider.now(); subscriber.next({ timestamp: timestampProvider ? now : timestamp, elapsed: now - start }); if (!subscriber.closed) { subscription.add(schedule(run)); } }; subscription.add(schedule(run)); return subscription; }); } /** * In the common case, where the timestamp provided by the rAF API is used, * we use this shared observable to reduce overhead. */ const DEFAULT_ANIMATION_FRAMES = animationFramesFactory();