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 AIS_AnimationProgressAIS_AnimationProgress29 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 a basic animation class. 35 //! AIS_Animation can be used as: 36 //! 37 //! - Animation Implementor 38 //! Sub-classes should override method AIS_Animation::update() to perform specific animation. 39 //! AIS package provides limited number of such animation atoms - classes AIS_AnimationObject and AIS_AnimationCamera, which could be enough for defining a simple animation. 40 //! In general case, application is expected defining own AIS_Animation sub-classes implementing application-specific animation logic 41 //! (e.g. another interpolation or another kind of transformations - like color transition and others). 42 //! The basic conception of AIS_Animation::update() is defining an exact scene state for the current presentation timestamp, 43 //! providing a smooth and continuous animation well defined at any time step and in any direction. 44 //! So that a time difference between two sequential drawn Viewer frames can vary from frame to frame without visual artifacts, 45 //! increasing rendering framerate would not lead to animation being executed too fast 46 //! and low framerate (on slow hardware) would not lead to animation played longer than defined duration. 47 //! Hence, implementation should avoid usage of incremental step logic or should apply it very carefully. 48 //! 49 //! - Animation Container 50 //! AIS_Animation (no sub-classing) can be used to aggregate a sequence of Animation items (children). 51 //! Each children should be defined with its own duration and start time (presentation timestamp). 52 //! It is possible defining collection of nested AIS_Animation items, so that within each container level 53 //! children define start playback time relative to its holder. 54 //! 55 //! - Animation playback Controller 56 //! It is suggested that application would define a single AIS_Animation instance (optional sub-classing) for controlling animation playback as whole. 57 //! Such controller should be filled in by other AIS_Animation as children objects, 58 //! and will be managed by application by calling StartTimer(), UpdateTimer() and IsStopped() methods. 59 //! 60 //! Note, that AIS_Animation::StartTimer() defines a timer calculating an elapsed time, not a multimedia timer executing Viewer updates at specific intervals! 61 //! Application should avoid using implicit and immediate Viewer updates to ensure that AIS_Animation::UpdateTimer() is called before each redrawing of a Viewer content. 62 //! Redrawing logic should be also managed at application level for managing a smooth animation 63 //! (by defining a multimedia timer provided by used GUI framework executing updates at desired framerate, or as continuous redraws in loop). 64 class AIS_Animation : public Standard_Transient 65 { 66 DEFINE_STANDARD_RTTIEXT(AIS_Animation, Standard_Transient) 67 public: 68 69 //! Creates empty animation. 70 Standard_EXPORT AIS_Animation (const TCollection_AsciiString& theAnimationName); 71 72 //! Destruct object, clear arguments 73 Standard_EXPORT virtual ~AIS_Animation(); 74 75 //! Animation name. Name() const76 const TCollection_AsciiString& Name() const { return myName; } 77 78 public: 79 80 //! @return start time of the animation in the timeline StartPts() const81 Standard_Real StartPts() const { return myPtsStart; } 82 83 //! Sets time limits for animation in the animation timeline SetStartPts(const Standard_Real thePtsStart)84 void SetStartPts (const Standard_Real thePtsStart) { myPtsStart = thePtsStart; } 85 86 //! @return duration of the animation in the timeline Duration() const87 Standard_Real Duration() const { return Max (myOwnDuration, myChildrenDuration); } 88 89 //! Update total duration considering all animations on timeline. 90 Standard_EXPORT void UpdateTotalDuration(); 91 92 //! Return true if duration is defined. HasOwnDuration() const93 Standard_Boolean HasOwnDuration() const { return myOwnDuration > 0.0; } 94 95 //! @return own duration of the animation in the timeline OwnDuration() const96 Standard_Real OwnDuration() const { return myOwnDuration; } 97 98 //! Defines duration of the animation. SetOwnDuration(const Standard_Real theDuration)99 void SetOwnDuration (const Standard_Real theDuration) { myOwnDuration = theDuration; } 100 101 //! Add single animation to the timeline. 102 //! @param theAnimation input animation 103 Standard_EXPORT void Add (const Handle(AIS_Animation)& theAnimation); 104 105 //! Clear animation timeline - remove all animations from it. 106 Standard_EXPORT void Clear(); 107 108 //! Return the child animation with the given name. 109 Standard_EXPORT Handle(AIS_Animation) Find (const TCollection_AsciiString& theAnimationName) const; 110 111 //! Remove the child animation. 112 Standard_EXPORT Standard_Boolean Remove (const Handle(AIS_Animation)& theAnimation); 113 114 //! Replace the child animation. 115 Standard_EXPORT Standard_Boolean Replace (const Handle(AIS_Animation)& theAnimationOld, 116 const Handle(AIS_Animation)& theAnimationNew); 117 118 //! Clears own children and then copy child animations from another object. 119 //! Copy also Start Time and Duration values. 120 Standard_EXPORT void CopyFrom (const Handle(AIS_Animation)& theOther); 121 122 //! Return sequence of child animations. Children() const123 const NCollection_Sequence<Handle(AIS_Animation)>& Children() const { return myAnimations; } 124 125 public: 126 127 //! Start animation with internally defined timer instance. 128 //! Calls ::Start() internally. 129 //! 130 //! Note, that this method initializes a timer calculating an elapsed time (presentation timestamps within AIS_Animation::UpdateTimer()), 131 //! not a multimedia timer executing Viewer updates at specific intervals! 132 //! Viewer redrawing should be managed at application level, so that AIS_Animation::UpdateTimer() is called once right before each redrawing of a Viewer content. 133 //! 134 //! @param theStartPts starting timer position (presentation timestamp) 135 //! @param thePlaySpeed playback speed (1.0 means normal speed) 136 //! @param theToUpdate flag to update defined animations to specified start position 137 //! @param theToStopTimer flag to pause timer at the starting position 138 Standard_EXPORT virtual void StartTimer (const Standard_Real theStartPts, 139 const Standard_Real thePlaySpeed, 140 const Standard_Boolean theToUpdate, 141 const Standard_Boolean theToStopTimer = Standard_False); 142 143 //! Update single frame of animation, update timer state 144 //! @return current time of timeline progress. 145 Standard_EXPORT virtual Standard_Real UpdateTimer(); 146 147 //! Return elapsed time. ElapsedTime() const148 Standard_Real ElapsedTime() const { return !myTimer.IsNull() ? myTimer->ElapsedTime() : 0.0; } 149 150 //! Return playback timer. Handle(Media_Timer)151 const Handle(Media_Timer)& Timer() const { return myTimer; } 152 153 //! Set playback timer. SetTimer(const Handle (Media_Timer)& theTimer)154 void SetTimer (const Handle(Media_Timer)& theTimer) { myTimer = theTimer; } 155 156 public: 157 158 //! Start animation. This method changes status of the animation to Started. 159 //! This status defines whether animation is to be performed in the timeline or not. 160 //! @param theToUpdate call Update() method 161 Standard_EXPORT virtual void Start (const Standard_Boolean theToUpdate); 162 163 //! Pause the process timeline. 164 Standard_EXPORT virtual void Pause(); 165 166 //! Stop animation. This method changed status of the animation to Stopped. 167 //! This status shows that animation will not be performed in the timeline or it is finished. 168 Standard_EXPORT virtual void Stop(); 169 170 //! Check if animation is to be performed in the animation timeline. 171 //! @return True if it is stopped of finished. IsStopped()172 bool IsStopped() { return myState != AnimationState_Started; } 173 174 //! Update single frame of animation, update timer state 175 //! @param thePts [in] the time moment within [0; Duration()] 176 //! @return True if timeline is in progress 177 Standard_EXPORT virtual Standard_Boolean Update (const Standard_Real thePts); 178 179 protected: 180 181 //! Process one step of the animation according to the input time progress, including all children. 182 //! Calls also ::update() to update own animation. 183 Standard_EXPORT virtual void updateWithChildren (const AIS_AnimationProgress& thePosition); 184 185 //! Update the own animation to specified position - should be overridden by sub-class. update(const AIS_AnimationProgress & theProgress)186 virtual void update (const AIS_AnimationProgress& theProgress) { (void )theProgress; } 187 188 protected: 189 190 //! Defines animation state. 191 enum AnimationState 192 { 193 AnimationState_Started, //!< animation is in progress 194 AnimationState_Stopped, //!< animation is finished, force stopped or not started 195 AnimationState_Paused //!< animation is paused and can be started from the pause moment 196 }; 197 198 protected: 199 200 Handle(Media_Timer) myTimer; 201 202 TCollection_AsciiString myName; //!< animation name 203 NCollection_Sequence<Handle(AIS_Animation)> 204 myAnimations; //!< sequence of child animations 205 206 AnimationState myState; //!< animation state - started, stopped of paused 207 Standard_Real myPtsStart; //!< time of start in the timeline 208 Standard_Real myOwnDuration; //!< duration of animation excluding children 209 Standard_Real myChildrenDuration; //!< duration of animation including children 210 211 }; 212 213 #endif // _AIS_Animation_HeaderFile 214