content/smil/nsSMILInstanceTime.h

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