dom/smil/SMILInstanceTime.h

   1 /* -*- Mode: C++; tab-width: 8; indent-tabs-mode: nil; c-basic-offset: 2 -*- */
   2 /* vim: set ts=8 sts=2 et sw=2 tw=80: */
   3 /* This Source Code Form is subject to the terms of the Mozilla Public
   4  * License, v. 2.0. If a copy of the MPL was not distributed with this
   5  * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
   6
   7 #ifndef DOM_SMIL_SMILINSTANCETIME_H_
   8 #define DOM_SMIL_SMILINSTANCETIME_H_
   9
  10 #include "nsISupportsImpl.h"
  11 #include "mozilla/SMILTimeValue.h"
  12
  13 namespace mozilla {
  14 class SMILInterval;
  15 class SMILTimeContainer;
  16 class SMILTimeValueSpec;
  17
  18 //----------------------------------------------------------------------
  19 // SMILInstanceTime
  20 //
  21 // An instant in document simple time that may be used in creating a new
  22 // interval.
  23 //
  24 // For an overview of how this class is related to other SMIL time classes see
  25 // the documentation in SMILTimeValue.h
  26 //
  27 // These objects are owned by an SMILTimedElement but MAY also be referenced
  28 // by:
  29 //
  30 // a) SMILIntervals that belong to the same SMILTimedElement and which refer
  31 //    to the SMILInstanceTimes which form the interval endpoints; and/or
  32 // b) SMILIntervals that belong to other SMILTimedElements but which need to
  33 //    update dependent instance times when they change or are deleted.
  34 //    E.g. for begin='a.begin', 'a' needs to inform dependent
  35 //    SMILInstanceTimes if its begin time changes. This notification is
  36 //    performed by the SMILInterval.
  37
  38 class SMILInstanceTime final {
  39  public:
  40   // Instance time source. Times generated by events, syncbase relationships,
  41   // and DOM calls behave differently in some circumstances such as when a timed
  42   // element is reset.
  43   enum SMILInstanceTimeSource {
  44     // No particularly significant source, e.g. offset time, 'indefinite'
  45     SOURCE_NONE,
  46     // Generated by a DOM call such as beginElement
  47     SOURCE_DOM,
  48     // Generated by a syncbase relationship
  49     SOURCE_SYNCBASE,
  50     // Generated by an event
  51     SOURCE_EVENT
  52   };
  53
  54   explicit SMILInstanceTime(const SMILTimeValue& aTime,
  55                             SMILInstanceTimeSource aSource = SOURCE_NONE,
  56                             SMILTimeValueSpec* aCreator = nullptr,
  57                             SMILInterval* aBaseInterval = nullptr);
  58
  59   void Unlink();
  60   void HandleChangedInterval(const SMILTimeContainer* aSrcContainer,
  61                              bool aBeginObjectChanged, bool aEndObjectChanged);
  62   void HandleDeletedInterval();
  63   void HandleFilteredInterval();
  64
  65   const SMILTimeValue& Time() const { return mTime; }
  66   const SMILTimeValueSpec* GetCreator() const { return mCreator; }
  67
  68   bool IsDynamic() const { return !!(mFlags & kDynamic); }
  69   bool IsFixedTime() const { return !(mFlags & kMayUpdate); }
  70   bool FromDOM() const { return !!(mFlags & kFromDOM); }
  71
  72   bool ShouldPreserve() const;
  73   void UnmarkShouldPreserve();
  74
  75   void AddRefFixedEndpoint();
  76   void ReleaseFixedEndpoint();
  77
  78   void DependentUpdate(const SMILTimeValue& aNewTime) {
  79     MOZ_ASSERT(!IsFixedTime(),
  80                "Updating an instance time that is not expected to be updated");
  81     mTime = aNewTime;
  82   }
  83
  84   bool IsDependent() const { return !!mBaseInterval; }
  85   bool IsDependentOn(const SMILInstanceTime& aOther) const;
  86   const SMILInterval* GetBaseInterval() const { return mBaseInterval; }
  87   const SMILInstanceTime* GetBaseTime() const;
  88
  89   bool SameTimeAndBase(const SMILInstanceTime& aOther) const {
  90     return mTime == aOther.mTime && GetBaseTime() == aOther.GetBaseTime();
  91   }
  92
  93   // Get and set a serial number which may be used by a containing class to
  94   // control the sort order of otherwise similar instance times.
  95   uint32_t Serial() const { return mSerial; }
  96   void SetSerial(uint32_t aIndex) { mSerial = aIndex; }
  97
  98   NS_INLINE_DECL_REFCOUNTING(SMILInstanceTime)
  99
 100  private:
 101   // Private destructor, to discourage deletion outside of Release():
 102   ~SMILInstanceTime();
 103
 104   void SetBaseInterval(SMILInterval* aBaseInterval);
 105
 106   SMILTimeValue mTime;
 107
 108   // Internal flags used to represent the behaviour of different instance times
 109   enum {
 110     // Indicates that this instance time was generated by an event or a DOM
 111     // call. Such instance times require special handling when (i) the owning
 112     // element is reset, (ii) when they are to be added as a new end instance
 113     // times (as per SMIL's event sensitivity contraints), and (iii) when
 114     // a backwards seek is performed and the timing model is reconstructed.
 115     kDynamic = 1,
 116
 117     // Indicates that this instance time is referred to by an
 118     // SMILTimeValueSpec and as such may be updated. Such instance time should
 119     // not be filtered out by the SMILTimedElement even if they appear to be
 120     // in the past as they may be updated to a future time.
 121     kMayUpdate = 2,
 122
 123     // Indicates that this instance time was generated from the DOM as opposed
 124     // to an SMILTimeValueSpec. When a 'begin' or 'end' attribute is set or
 125     // reset we should clear all the instance times that have been generated by
 126     // that attribute (and hence an SMILTimeValueSpec), but not those from the
 127     // DOM.
 128     kFromDOM = 4,
 129
 130     // Indicates that this instance time was used as the endpoint of an interval
 131     // that has been filtered or removed. However, since it is a dynamic time it
 132     // should be preserved and not filtered.
 133     kWasDynamicEndpoint = 8
 134   };
 135   uint8_t mFlags;         // Combination of kDynamic, kMayUpdate, etc.
 136   mutable bool mVisited;  // Cycle tracking
 137
 138   // Additional reference count to determine if this instance time is currently
 139   // used as a fixed endpoint in any intervals. Instance times that are used in
 140   // this way should not be removed when the owning SMILTimedElement removes
 141   // instance times in response to a restart or in an attempt to free up memory
 142   // by filtering out old instance times.
 143   //
 144   // Instance times are only shared in a few cases, namely:
 145   // a) early ends,
 146   // b) zero-duration intervals,
 147   // c) momentarily whilst establishing new intervals and updating the current
 148   //    interval, and
 149   // d) trimmed intervals
 150   // Hence the limited range of a uint16_t should be more than adequate.
 151   uint16_t mFixedEndpointRefCnt;
 152
 153   uint32_t mSerial;  // A serial number used by the containing class to
 154                      // specify the sort order for instance times with the
 155                      // same mTime.
 156
 157   SMILTimeValueSpec* mCreator;  // The SMILTimeValueSpec object that created
 158                                 // us. (currently only needed for syncbase
 159                                 // instance times.)
 160   SMILInterval* mBaseInterval;  // Interval from which this time is derived
 161                                 // (only used for syncbase instance times)
 162 };
 163
 164 }  // namespace mozilla
 165
 166 #endif  // DOM_SMIL_SMILINSTANCETIME_H_