gecko-dev/dom/animation/Animation.h

/* -*- Mode: C++; tab-width: 8; indent-tabs-mode: nil; c-basic-offset: 2 -*- */
/* vim: set ts=8 sts=2 et sw=2 tw=80: */
/* This Source Code Form is subject to the terms of the Mozilla Public
 * License, v. 2.0. If a copy of the MPL was not distributed with this
 * file, You can obtain one at http://mozilla.org/MPL/2.0/. */

#ifndef mozilla_dom_Animation_h
#define mozilla_dom_Animation_h

#include "nsWrapperCache.h"
#include "nsCycleCollectionParticipant.h"
#include "mozilla/AnimationPerformanceWarning.h"
#include "mozilla/Attributes.h"
#include "mozilla/CycleCollectedJSContext.h"
#include "mozilla/DOMEventTargetHelper.h"
#include "mozilla/EffectCompositor.h" // For EffectCompositor::CascadeLevel
#include "mozilla/LinkedList.h"
#include "mozilla/TimeStamp.h" // for TimeStamp, TimeDuration
#include "mozilla/dom/AnimationBinding.h" // for AnimationPlayState
#include "mozilla/dom/AnimationEffect.h"
#include "mozilla/dom/AnimationTimeline.h"
#include "mozilla/dom/Promise.h"
#include "nsCSSPropertyID.h"
#include "nsIGlobalObject.h"

// X11 has a #define for CurrentTime.
#ifdef CurrentTime
#undef CurrentTime
#endif

// GetCurrentTime is defined in winbase.h as zero argument macro forwarding to
// GetTickCount().
#ifdef GetCurrentTime
#undef GetCurrentTime
#endif

struct JSContext;
class nsCSSPropertyIDSet;
class nsIDocument;
class nsIFrame;

namespace mozilla {

struct AnimationRule;

namespace dom {

class AsyncFinishNotification;
class CSSAnimation;
class CSSTransition;

class Animation
  : public DOMEventTargetHelper
  , public LinkedListElement<Animation>
{
protected:
  virtual ~Animation() {}

public:
  explicit Animation(nsIGlobalObject* aGlobal)
    : DOMEventTargetHelper(aGlobal)
    , mPlaybackRate(1.0)
    , mAnimationIndex(sNextAnimationIndex++)
    , mCachedChildIndex(-1)
    , mPendingState(PendingState::NotPending)
    , mFinishedAtLastComposeStyle(false)
    , mIsRelevant(false)
    , mFinishedIsResolved(false)
    , mSyncWithGeometricAnimations(false)
  {
  }

  NS_DECL_ISUPPORTS_INHERITED
  NS_DECL_CYCLE_COLLECTION_CLASS_INHERITED(Animation,
                                           DOMEventTargetHelper)

  nsIGlobalObject* GetParentObject() const { return GetOwnerGlobal(); }
  virtual JSObject* WrapObject(JSContext* aCx,
                               JS::Handle<JSObject*> aGivenProto) override;

  virtual CSSAnimation* AsCSSAnimation() { return nullptr; }
  virtual const CSSAnimation* AsCSSAnimation() const { return nullptr; }
  virtual CSSTransition* AsCSSTransition() { return nullptr; }
  virtual const CSSTransition* AsCSSTransition() const { return nullptr; }

  /**
   * Flag to pass to Play to indicate whether or not it should automatically
   * rewind the current time to the start point if the animation is finished.
   * For regular calls to play() from script we should do this, but when a CSS
   * animation's animation-play-state changes we shouldn't rewind the animation.
   */
  enum class LimitBehavior {
    AutoRewind,
    Continue
  };

  // Animation interface methods
  static already_AddRefed<Animation>
  Constructor(const GlobalObject& aGlobal,
              AnimationEffect* aEffect,
              const Optional<AnimationTimeline*>& aTimeline,
              ErrorResult& aRv);
  void GetId(nsAString& aResult) const { aResult = mId; }
  void SetId(const nsAString& aId);
  AnimationEffect* GetEffect() const { return mEffect; }
  void SetEffect(AnimationEffect* aEffect);
  AnimationTimeline* GetTimeline() const { return mTimeline; }
  void SetTimeline(AnimationTimeline* aTimeline);
  Nullable<TimeDuration> GetStartTime() const { return mStartTime; }
  void SetStartTime(const Nullable<TimeDuration>& aNewStartTime);
  Nullable<TimeDuration> GetCurrentTime() const {
    return GetCurrentTimeForHoldTime(mHoldTime);
  }
  void SetCurrentTime(const TimeDuration& aNewCurrentTime);
  double PlaybackRate() const { return mPlaybackRate; }
  void SetPlaybackRate(double aPlaybackRate);
  AnimationPlayState PlayState() const;
  bool Pending() const { return mPendingState != PendingState::NotPending; }
  virtual Promise* GetReady(ErrorResult& aRv);
  Promise* GetFinished(ErrorResult& aRv);
  void Cancel();
  void Finish(ErrorResult& aRv);
  virtual void Play(ErrorResult& aRv, LimitBehavior aLimitBehavior);
  virtual void Pause(ErrorResult& aRv);
  void Reverse(ErrorResult& aRv);
  void UpdatePlaybackRate(double aPlaybackRate);
  bool IsRunningOnCompositor() const;
  IMPL_EVENT_HANDLER(finish);
  IMPL_EVENT_HANDLER(cancel);

  // Wrapper functions for Animation DOM methods when called
  // from script.
  //
  // We often use the same methods internally and from script but when called
  // from script we (or one of our subclasses) perform extra steps such as
  // flushing style or converting the return type.
  Nullable<double> GetStartTimeAsDouble() const;
  void SetStartTimeAsDouble(const Nullable<double>& aStartTime);
  Nullable<double> GetCurrentTimeAsDouble() const;
  void SetCurrentTimeAsDouble(const Nullable<double>& aCurrentTime,
                              ErrorResult& aRv);
  virtual AnimationPlayState PlayStateFromJS() const { return PlayState(); }
  virtual bool PendingFromJS() const { return Pending(); }
  virtual void PlayFromJS(ErrorResult& aRv)
  {
    Play(aRv, LimitBehavior::AutoRewind);
  }
  /**
   * PauseFromJS is currently only here for symmetry with PlayFromJS but
   * in future we will likely have to flush style in
   * CSSAnimation::PauseFromJS so we leave it for now.
   */
  void PauseFromJS(ErrorResult& aRv) { Pause(aRv); }

  // Wrapper functions for Animation DOM methods when called from style.

  virtual void CancelFromStyle() { CancelNoUpdate(); }
  void SetTimelineNoUpdate(AnimationTimeline* aTimeline);
  void SetEffectNoUpdate(AnimationEffect* aEffect);

  virtual void Tick();
  bool NeedsTicks() const
  {
    return Pending() || PlayState() == AnimationPlayState::Running;
  }

  /**
   * Set the time to use for starting or pausing a pending animation.
   *
   * Typically, when an animation is played, it does not start immediately but
   * is added to a table of pending animations on the document of its effect.
   * In the meantime it sets its hold time to the time from which playback
   * should begin.
   *
   * When the document finishes painting, any pending animations in its table
   * are marked as being ready to start by calling TriggerOnNextTick.
   * The moment when the paint completed is also recorded, converted to a
   * timeline time, and passed to StartOnTick. This is so that when these
   * animations do start, they can be timed from the point when painting
   * completed.
   *
   * After calling TriggerOnNextTick, animations remain in the pending state
   * until the next refresh driver tick. At that time they transition out of
   * the pending state using the time passed to TriggerOnNextTick as the
   * effective time at which they resumed.
   *
   * This approach means that any setup time required for performing the
   * initial paint of an animation such as layerization is not deducted from
   * the running time of the animation. Without this we can easily drop the
   * first few frames of an animation, or, on slower devices, the whole
   * animation.
   *
   * Furthermore:
   *
   * - Starting the animation immediately when painting finishes is problematic
   *   because the start time of the animation will be ahead of its timeline
   *   (since the timeline time is based on the refresh driver time).
   *   That's a problem because the animation is playing but its timing
   *   suggests it starts in the future. We could update the timeline to match
   *   the start time of the animation but then we'd also have to update the
   *   timing and style of all animations connected to that timeline or else be
   *   stuck in an inconsistent state until the next refresh driver tick.
   *
   * - If we simply use the refresh driver time on its next tick, the lag
   *   between triggering an animation and its effective start is unacceptably
   *   long.
   *
   * For pausing, we apply the same asynchronous approach. This is so that we
   * synchronize with animations that are running on the compositor. Otherwise
   * if the main thread lags behind the compositor there will be a noticeable
   * jump backwards when the main thread takes over. Even though main thread
   * animations could be paused immediately, we do it asynchronously for
   * consistency and so that animations paused together end up in step.
   *
   * Note that the caller of this method is responsible for removing the
   * animation from any PendingAnimationTracker it may have been added to.
   */
  void TriggerOnNextTick(const Nullable<TimeDuration>& aReadyTime);
  /**
   * Testing only: Start or pause a pending animation using the current
   * timeline time. This is used to support existing tests that expect
   * animations to begin immediately. Ideally we would rewrite the those tests
   * and get rid of this method, but there are a lot of them.
   *
   * As with TriggerOnNextTick, the caller of this method is responsible for
   * removing the animation from any PendingAnimationTracker it may have been
   * added to.
   */
  void TriggerNow();
  /**
   * When TriggerOnNextTick is called, we store the ready time but we don't
   * apply it until the next tick. In the meantime, GetStartTime() will return
   * null.
   *
   * However, if we build layer animations again before the next tick, we
   * should initialize them with the start time that GetStartTime() will return
   * on the next tick.
   *
   * If we were to simply set the start time of layer animations to null, their
   * start time would be updated to the current wallclock time when rendering
   * finishes, thus making them out of sync with the start time stored here.
   * This, in turn, will make the animation jump backwards when we build
   * animations on the next tick and apply the start time stored here.
   *
   * This method returns the start time, if resolved. Otherwise, if we have
   * a pending ready time, it returns the corresponding start time. If neither
   * of those are available, it returns null.
   */
  Nullable<TimeDuration> GetCurrentOrPendingStartTime() const;

  /**
   * As with the start time, we should use the pending playback rate when
   * producing layer animations.
   */
  double CurrentOrPendingPlaybackRate() const
  {
    return mPendingPlaybackRate.valueOr(mPlaybackRate);
  }
  bool HasPendingPlaybackRate() const { return mPendingPlaybackRate.isSome(); }

  /**
   * The following relationship from the definition of the 'current time' is
   * re-used in many algorithms so we extract it here into a static method that
   * can be re-used:
   *
   *   current time = (timeline time - start time) * playback rate
   *
   * As per https://drafts.csswg.org/web-animations-1/#current-time
   */
  static TimeDuration CurrentTimeFromTimelineTime(
    const TimeDuration& aTimelineTime,
    const TimeDuration& aStartTime,
    float aPlaybackRate)
  {
    return (aTimelineTime - aStartTime).MultDouble(aPlaybackRate);
  }

  /**
   * As with calculating the current time, we often need to calculate a start
   * time from a current time. The following method simply inverts the current
   * time relationship.
   *
   * In each case where this is used, the desired behavior for playbackRate ==
   * 0 is to return the specified timeline time (often referred to as the ready
   * time).
   */
  static TimeDuration StartTimeFromTimelineTime(
    const TimeDuration& aTimelineTime,
    const TimeDuration& aCurrentTime,
    float aPlaybackRate)
  {
    TimeDuration result = aTimelineTime;
    if (aPlaybackRate == 0) {
      return result;
    }

    result -= aCurrentTime.MultDouble(1.0 / aPlaybackRate);
    return result;
  }

  /**
   * Converts a time in the timescale of this Animation's currentTime, to a
   * TimeStamp. Returns a null TimeStamp if the conversion cannot be performed
   * because of the current state of this Animation (e.g. it has no timeline, a
   * zero playbackRate, an unresolved start time etc.) or the value of the time
   * passed-in (e.g. an infinite time).
   */
  TimeStamp AnimationTimeToTimeStamp(const StickyTimeDuration& aTime) const;

  // Converts an AnimationEvent's elapsedTime value to an equivalent TimeStamp
  // that can be used to sort events by when they occurred.
  TimeStamp ElapsedTimeToTimeStamp(const StickyTimeDuration& aElapsedTime) const;

  bool IsPausedOrPausing() const
  {
    return PlayState() == AnimationPlayState::Paused;
  }

  bool HasCurrentEffect() const
  {
    return GetEffect() && GetEffect()->IsCurrent();
  }
  bool IsInEffect() const
  {
    return GetEffect() && GetEffect()->IsInEffect();
  }

  bool IsPlaying() const
  {
    return mPlaybackRate != 0.0 &&
           mTimeline &&
           !mTimeline->GetCurrentTime().IsNull() &&
           PlayState() == AnimationPlayState::Running;
  }

  bool ShouldBeSynchronizedWithMainThread(
    nsCSSPropertyID aProperty,
    const nsIFrame* aFrame,
    AnimationPerformanceWarning::Type& aPerformanceWarning) const;

  bool IsRelevant() const { return mIsRelevant; }
  void UpdateRelevance();

  /**
   * Returns true if this Animation has a lower composite order than aOther.
   */
  bool HasLowerCompositeOrderThan(const Animation& aOther) const;

   /**
   * Returns the level at which the effect(s) associated with this Animation
   * are applied to the CSS cascade.
   */
  virtual EffectCompositor::CascadeLevel CascadeLevel() const
  {
    return EffectCompositor::CascadeLevel::Animations;
  }

  /**
   * Returns true if this animation does not currently need to update
   * style on the main thread (e.g. because it is empty, or is
   * running on the compositor).
   */
  bool CanThrottle() const;

  /**
   * Updates various bits of state that we need to update as the result of
   * running ComposeStyle().
   * See the comment of KeyframeEffect::WillComposeStyle for more detail.
   */
  void WillComposeStyle();

  /**
   * Updates |aComposeResult| with the animation values of this animation's
   * effect, if any.
   * Any properties contained in |aPropertiesToSkip| will not be added or
   * updated in |aComposeResult|.
   */
  void ComposeStyle(RawServoAnimationValueMap& aComposeResult,
                    const nsCSSPropertyIDSet& aPropertiesToSkip);

  void NotifyEffectTimingUpdated();
  void NotifyGeometricAnimationsStartingThisFrame();

  /**
   * Reschedule pending pause or pending play tasks when updating the target
   * effect.
   *
   * If we are pending, we will either be registered in the pending animation
   * tracker and have a null pending ready time, or, after our effect has been
   * painted, we will be removed from the tracker and assigned a pending ready
   * time.
   *
   * When the target effect is updated, we'll typically need to repaint so for
   * the latter case where we already have a pending ready time, clear it and put
   * ourselves back in the pending animation tracker.
   */
  void ReschedulePendingTasks();

  /**
   * Used by subclasses to synchronously queue a cancel event in situations
   * where the Animation may have been cancelled.
   *
   * We need to do this synchronously because after a CSS animation/transition
   * is canceled, it will be released by its owning element and may not still
   * exist when we would normally go to queue events on the next tick.
   */
  virtual void MaybeQueueCancelEvent(const StickyTimeDuration& aActiveTime) {};

  int32_t& CachedChildIndexRef() { return mCachedChildIndex; }

protected:
  void SilentlySetCurrentTime(const TimeDuration& aNewCurrentTime);
  void CancelNoUpdate();
  void PlayNoUpdate(ErrorResult& aRv, LimitBehavior aLimitBehavior);
  void ResumeAt(const TimeDuration& aReadyTime);
  void PauseAt(const TimeDuration& aReadyTime);
  void FinishPendingAt(const TimeDuration& aReadyTime)
  {
    if (mPendingState == PendingState::PlayPending) {
      ResumeAt(aReadyTime);
    } else if (mPendingState == PendingState::PausePending) {
      PauseAt(aReadyTime);
    } else {
      MOZ_ASSERT_UNREACHABLE("Can't finish pending if we're not in a pending state");
    }
  }
  void ApplyPendingPlaybackRate()
  {
    if (mPendingPlaybackRate) {
      mPlaybackRate = *mPendingPlaybackRate;
      mPendingPlaybackRate.reset();
    }
  }

  /**
   * Finishing behavior depends on if changes to timing occurred due
   * to a seek or regular playback.
   */
  enum class SeekFlag {
    NoSeek,
    DidSeek
  };

  enum class SyncNotifyFlag {
    Sync,
    Async
  };

  virtual void UpdateTiming(SeekFlag aSeekFlag,
                            SyncNotifyFlag aSyncNotifyFlag);
  void UpdateFinishedState(SeekFlag aSeekFlag,
                           SyncNotifyFlag aSyncNotifyFlag);
  void UpdateEffect();
  /**
   * Flush all pending styles other than throttled animation styles (e.g.
   * animations running on the compositor).
   */
  void FlushUnanimatedStyle() const;
  void PostUpdate();
  void ResetFinishedPromise();
  void MaybeResolveFinishedPromise();
  void DoFinishNotification(SyncNotifyFlag aSyncNotifyFlag);
  friend class AsyncFinishNotification;
  void DoFinishNotificationImmediately(MicroTaskRunnable* aAsync = nullptr);
  void QueuePlaybackEvent(const nsAString& aName,
                          TimeStamp&& aScheduledEventTime);

  /**
   * Remove this animation from the pending animation tracker and reset
   * mPendingState as necessary. The caller is responsible for resolving or
   * aborting the mReady promise as necessary.
   */
  void CancelPendingTasks();

  /**
   * Performs the same steps as CancelPendingTasks and also rejects and
   * recreates the ready promise if the animation was pending.
   */
  void ResetPendingTasks();

  /**
   * Returns true if this animation is not only play-pending, but has
   * yet to be given a pending ready time. This roughly corresponds to
   * animations that are waiting to be painted (since we set the pending
   * ready time at the end of painting). Identifying such animations is
   * useful because in some cases animations that are painted together
   * may need to be synchronized.
   *
   * We don't, however, want to include animations with a fixed start time such
   * as animations that are simply having their playbackRate updated or which
   * are resuming from an aborted pause.
   */
  bool IsNewlyStarted() const {
    return mPendingState == PendingState::PlayPending &&
           mPendingReadyTime.IsNull() &&
           mStartTime.IsNull();
  }
  bool IsPossiblyOrphanedPendingAnimation() const;
  StickyTimeDuration EffectEnd() const;

  Nullable<TimeDuration> GetCurrentTimeForHoldTime(
    const Nullable<TimeDuration>& aHoldTime) const;
  Nullable<TimeDuration> GetUnconstrainedCurrentTime() const
  {
    return GetCurrentTimeForHoldTime(Nullable<TimeDuration>());
  }

  // Earlier side of the elapsed time range reported in CSS Animations and CSS
  // Transitions events.
  //
  // https://drafts.csswg.org/css-animations-2/#interval-start
  // https://drafts.csswg.org/css-transitions-2/#interval-start
  StickyTimeDuration
  IntervalStartTime(const StickyTimeDuration& aActiveDuration) const
  {
    MOZ_ASSERT(AsCSSTransition() || AsCSSAnimation(),
               "Should be called for CSS animations or transitions");
    static constexpr StickyTimeDuration zeroDuration = StickyTimeDuration();
    return std::max(
      std::min(StickyTimeDuration(-mEffect->SpecifiedTiming().Delay()),
               aActiveDuration),
      zeroDuration);
  }

  // Later side of the elapsed time range reported in CSS Animations and CSS
  // Transitions events.
  //
  // https://drafts.csswg.org/css-animations-2/#interval-end
  // https://drafts.csswg.org/css-transitions-2/#interval-end
  StickyTimeDuration
  IntervalEndTime(const StickyTimeDuration& aActiveDuration) const
  {
    MOZ_ASSERT(AsCSSTransition() || AsCSSAnimation(),
               "Should be called for CSS animations or transitions");

    static constexpr StickyTimeDuration zeroDuration = StickyTimeDuration();
    return std::max(
      std::min((EffectEnd() - mEffect->SpecifiedTiming().Delay()),
               aActiveDuration),
      zeroDuration);
  }

  TimeStamp GetTimelineCurrentTimeAsTimeStamp() const
  {
    return mTimeline ? mTimeline->GetCurrentTimeAsTimeStamp() : TimeStamp();
  }

  nsIDocument* GetRenderedDocument() const;
  nsIDocument* GetTimelineDocument() const;

  RefPtr<AnimationTimeline> mTimeline;
  RefPtr<AnimationEffect> mEffect;
  // The beginning of the delay period.
  Nullable<TimeDuration> mStartTime; // Timeline timescale
  Nullable<TimeDuration> mHoldTime;  // Animation timescale
  Nullable<TimeDuration> mPendingReadyTime; // Timeline timescale
  Nullable<TimeDuration> mPreviousCurrentTime; // Animation timescale
  double mPlaybackRate;
  Maybe<double> mPendingPlaybackRate;

  // A Promise that is replaced on each call to Play()
  // and fulfilled when Play() is successfully completed.
  // This object is lazily created by GetReady.
  // See http://drafts.csswg.org/web-animations/#current-ready-promise
  RefPtr<Promise> mReady;

  // A Promise that is resolved when we reach the end of the effect, or
  // 0 when playing backwards. The Promise is replaced if the animation is
  // finished but then a state change makes it not finished.
  // This object is lazily created by GetFinished.
  // See http://drafts.csswg.org/web-animations/#current-finished-promise
  RefPtr<Promise> mFinished;

  static uint64_t sNextAnimationIndex;

  // The relative position of this animation within the global animation list.
  // This is kNoIndex while the animation is in the idle state and is updated
  // each time the animation transitions out of the idle state.
  //
  // Note that subclasses such as CSSTransition and CSSAnimation may repurpose
  // this member to implement their own brand of sorting. As a result, it is
  // possible for two different objects to have the same index.
  uint64_t mAnimationIndex;

  // While ordering Animation objects for event dispatch, the index of the
  // target node in its parent may be cached in mCachedChildIndex.
  int32_t mCachedChildIndex;

  // Indicates if the animation is in the pending state (and what state it is
  // waiting to enter when it finished pending). We use this rather than
  // checking if this animation is tracked by a PendingAnimationTracker because
  // the animation will continue to be pending even after it has been removed
  // from the PendingAnimationTracker while it is waiting for the next tick
  // (see TriggerOnNextTick for details).
  enum class PendingState : uint8_t
  {
    NotPending,
    PlayPending,
    PausePending
  };
  PendingState mPendingState;

  bool mFinishedAtLastComposeStyle;
  // Indicates that the animation should be exposed in an element's
  // getAnimations() list.
  bool mIsRelevant;

  // True if mFinished is resolved or would be resolved if mFinished has
  // yet to be created. This is not set when mFinished is rejected since
  // in that case mFinished is immediately reset to represent a new current
  // finished promise.
  bool mFinishedIsResolved;

  // True if this animation was triggered at the same time as one or more
  // geometric animations and hence we should run any transform animations on
  // the main thread.
  bool mSyncWithGeometricAnimations;

  RefPtr<MicroTaskRunnable> mFinishNotificationTask;

  nsString mId;
};

} // namespace dom
} // namespace mozilla

#endif // mozilla_dom_Animation_h