src/AIS/AIS_Animation.hxx

   1 // Created by: Anastasia BORISOVA
   2 // Copyright (c) 2016 OPEN CASCADE SAS
   3 //
   4 // This file is part of Open CASCADE Technology software library.
   5 //
   6 // This library is free software; you can redistribute it and/or modify it under
   7 // the terms of the GNU Lesser General Public License version 2.1 as published
   8 // by the Free Software Foundation, with special exception defined in the file
   9 // OCCT_LGPL_EXCEPTION.txt. Consult the file LICENSE_LGPL_21.txt included in OCCT
  10 // distribution for complete text of the license and disclaimer of any warranty.
  11 //
  12 // Alternatively, this file may be used under the terms of Open CASCADE
  13 // commercial license or contractual agreement.
  14
  15 #ifndef _AIS_Animation_HeaderFile
  16 #define _AIS_Animation_HeaderFile
  17
  18 #include <AIS_AnimationTimer.hxx>
  19 #include <NCollection_Sequence.hxx>
  20 #include <TCollection_AsciiString.hxx>
  21
  22 //! Structure defining current animation progress.
  23 struct AIS_AnimationProgress
  24 {
  25   Standard_Real Pts;             //!< global presentation timestamp
  26   Standard_Real LocalPts;        //!< presentation within current animation
  27   Standard_Real LocalNormalized; //!< normalized position within current animation within 0..1 range
  28
  29   AIS_AnimationProgress() : Pts (-1.0), LocalPts (-1.0), LocalNormalized (-1.0) {}
  30 };
  31
  32 DEFINE_STANDARD_HANDLE(AIS_Animation, Standard_Transient)
  33
  34 //! Class represents single animation.
  35 //! It is defined with:
  36 //! - Start time on the timeline started from 0, in seconds
  37 //! - Duration, in seconds
  38 //! - virtual method Update() for handling an update
  39 class AIS_Animation : public Standard_Transient
  40 {
  41   DEFINE_STANDARD_RTTIEXT(AIS_Animation, Standard_Transient)
  42 public:
  43
  44   //! Creates empty animation.
  45   Standard_EXPORT AIS_Animation (const TCollection_AsciiString& theAnimationName);
  46
  47   //! Destruct object, clear arguments
  48   Standard_EXPORT virtual ~AIS_Animation();
  49
  50   //! Animation name.
  51   const TCollection_AsciiString& Name() const { return myName; }
  52
  53 public:
  54
  55   //! @return start time of the animation in the timeline
  56   Standard_Real StartPts() const { return myPtsStart; }
  57
  58   //! Sets time limits for animation in the animation timeline
  59   void SetStartPts (const Standard_Real thePtsStart) { myPtsStart = thePtsStart; }
  60
  61   //! @return duration of the animation in the timeline
  62   Standard_Real Duration() const { return Max (myOwnDuration, myChildrenDuration); }
  63
  64   //! Update total duration considering all animations on timeline.
  65   Standard_EXPORT void UpdateTotalDuration();
  66
  67   //! Return true if duration is defined.
  68   Standard_Boolean HasOwnDuration() const { return myOwnDuration > 0.0; }
  69
  70   //! @return own duration of the animation in the timeline
  71   Standard_Real OwnDuration() const { return myOwnDuration; }
  72
  73   //! Defines duration of the animation.
  74   void SetOwnDuration (const Standard_Real theDuration) { myOwnDuration = theDuration; }
  75
  76   //! Add single animation to the timeline.
  77   //! @param theAnimation input animation
  78   Standard_EXPORT void Add (const Handle(AIS_Animation)& theAnimation);
  79
  80   //! Clear animation timeline - remove all animations from it.
  81   Standard_EXPORT void Clear();
  82
  83   //! Return the child animation with the given name.
  84   Standard_EXPORT Handle(AIS_Animation) Find (const TCollection_AsciiString& theAnimationName) const;
  85
  86   //! Remove the child animation.
  87   Standard_EXPORT Standard_Boolean Remove (const Handle(AIS_Animation)& theAnimation);
  88
  89   //! Replace the child animation.
  90   Standard_EXPORT Standard_Boolean Replace (const Handle(AIS_Animation)& theAnimationOld,
  91                                             const Handle(AIS_Animation)& theAnimationNew);
  92
  93   //! Clears own children and then copy child animations from another object.
  94   //! Copy also Start Time and Duration values.
  95   Standard_EXPORT void CopyFrom (const Handle(AIS_Animation)& theOther);
  96
  97   //! Return sequence of child animations.
  98   const NCollection_Sequence<Handle(AIS_Animation)>& Children() const { return myAnimations; }
  99
 100 public:
 101
 102   //! Start animation with internally defined timer instance.
 103   //! Calls ::Start() internally.
 104   //! @param theStartPts    starting timer position (presentation timestamp)
 105   //! @param thePlaySpeed   playback speed (1.0 means normal speed)
 106   //! @param theToUpdate    flag to update defined animations to specified start position
 107   //! @param theToStopTimer flag to pause timer at the starting position
 108   Standard_EXPORT virtual void StartTimer (const Standard_Real    theStartPts,
 109                                            const Standard_Real    thePlaySpeed,
 110                                            const Standard_Boolean theToUpdate,
 111                                            const Standard_Boolean theToStopTimer = Standard_False);
 112
 113   //! Update single frame of animation, update timer state
 114   //! @return current time of timeline progress.
 115   Standard_EXPORT virtual Standard_Real UpdateTimer();
 116
 117   //! Return elapsed time.
 118   Standard_Real ElapsedTime() const { return !myTimer.IsNull() ? myTimer->ElapsedTime() : 0.0; }
 119
 120 public:
 121
 122   //! Start animation. This method changes status of the animation to Started.
 123   //! This status defines whether animation is to be performed in the timeline or not.
 124   //! @param theToUpdate call Update() method
 125   Standard_EXPORT virtual void Start (const Standard_Boolean theToUpdate);
 126
 127   //! Pause the process timeline.
 128   Standard_EXPORT virtual void Pause();
 129
 130   //! Stop animation. This method changed status of the animation to Stopped.
 131   //! This status shows that animation will not be performed in the timeline or it is finished.
 132   Standard_EXPORT virtual void Stop();
 133
 134   //! Check if animation is to be performed in the animation timeline.
 135   //! @return True if it is stopped of finished.
 136   bool IsStopped() { return myState != AnimationState_Started; }
 137
 138   //! Update single frame of animation, update timer state
 139   //! @param thePts [in] the time moment within [0; Duration()]
 140   //! @return True if timeline is in progress
 141   Standard_EXPORT virtual Standard_Boolean Update (const Standard_Real thePts);
 142
 143 protected:
 144
 145   //! Process one step of the animation according to the input time progress, including all children.
 146   //! Calls also ::update() to update own animation.
 147   Standard_EXPORT virtual void updateWithChildren (const AIS_AnimationProgress& thePosition);
 148
 149   //! Update the own animation to specified position - should be overridden by sub-class.
 150   virtual void update (const AIS_AnimationProgress& theProgress) { (void )theProgress; }
 151
 152 protected:
 153
 154   //! Defines animation state.
 155   enum AnimationState
 156   {
 157     AnimationState_Started, //!< animation is in progress
 158     AnimationState_Stopped, //!< animation is finished, force stopped or not started
 159     AnimationState_Paused   //!< animation is paused and can be started from the pause moment
 160   };
 161
 162 protected:
 163
 164   Handle(AIS_AnimationTimer) myTimer;
 165
 166   TCollection_AsciiString myName;           //!< animation name
 167   NCollection_Sequence<Handle(AIS_Animation)>
 168                         myAnimations;       //!< sequence of child animations
 169
 170   AnimationState        myState;            //!< animation state - started, stopped of paused
 171   Standard_Real         myPtsStart;         //!< time of start in the timeline
 172   Standard_Real         myOwnDuration;      //!< duration of animation excluding children
 173   Standard_Real         myChildrenDuration; //!< duration of animation including children
 174
 175 };
 176
 177 #endif // _AIS_Animation_HeaderFile