1 // Created by: Anastasia BORISOVA
2 // Copyright (c) 2016 OPEN CASCADE SAS
4 // This file is part of Open CASCADE Technology software library.
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.
12 // Alternatively, this file may be used under the terms of Open CASCADE
13 // commercial license or contractual agreement.
15 #ifndef _AIS_Animation_HeaderFile
16 #define _AIS_Animation_HeaderFile
18 #include <AIS_AnimationTimer.hxx>
19 #include <NCollection_Sequence.hxx>
20 #include <TCollection_AsciiString.hxx>
22 //! Structure defining current animation progress.
23 struct AIS_AnimationProgress
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
29 AIS_AnimationProgress() : Pts (-1.0), LocalPts (-1.0), LocalNormalized (-1.0) {}
32 DEFINE_STANDARD_HANDLE(AIS_Animation, Standard_Transient)
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
41 DEFINE_STANDARD_RTTIEXT(AIS_Animation, Standard_Transient)
44 //! Creates empty animation.
45 Standard_EXPORT AIS_Animation (const TCollection_AsciiString& theAnimationName);
47 //! Destruct object, clear arguments
48 Standard_EXPORT virtual ~AIS_Animation();
51 const TCollection_AsciiString& Name() const { return myName; }
55 //! @return start time of the animation in the timeline
56 Standard_Real StartPts() const { return myPtsStart; }
58 //! Sets time limits for animation in the animation timeline
59 void SetStartPts (const Standard_Real thePtsStart) { myPtsStart = thePtsStart; }
61 //! @return duration of the animation in the timeline
62 Standard_Real Duration() const { return Max (myOwnDuration, myChildrenDuration); }
64 //! Update total duration considering all animations on timeline.
65 Standard_EXPORT void UpdateTotalDuration();
67 //! Return true if duration is defined.
68 Standard_Boolean HasOwnDuration() const { return myOwnDuration > 0.0; }
70 //! @return own duration of the animation in the timeline
71 Standard_Real OwnDuration() const { return myOwnDuration; }
73 //! Defines duration of the animation.
74 void SetOwnDuration (const Standard_Real theDuration) { myOwnDuration = theDuration; }
76 //! Add single animation to the timeline.
77 //! @param theAnimation input animation
78 Standard_EXPORT void Add (const Handle(AIS_Animation)& theAnimation);
80 //! Clear animation timeline - remove all animations from it.
81 Standard_EXPORT void Clear();
83 //! Return the child animation with the given name.
84 Standard_EXPORT Handle(AIS_Animation) Find (const TCollection_AsciiString& theAnimationName) const;
86 //! Remove the child animation.
87 Standard_EXPORT Standard_Boolean Remove (const Handle(AIS_Animation)& theAnimation);
89 //! Replace the child animation.
90 Standard_EXPORT Standard_Boolean Replace (const Handle(AIS_Animation)& theAnimationOld,
91 const Handle(AIS_Animation)& theAnimationNew);
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);
97 //! Return sequence of child animations.
98 const NCollection_Sequence<Handle(AIS_Animation)>& Children() const { return myAnimations; }
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);
113 //! Update single frame of animation, update timer state
114 //! @return current time of timeline progress.
115 Standard_EXPORT virtual Standard_Real UpdateTimer();
117 //! Return elapsed time.
118 Standard_Real ElapsedTime() const { return !myTimer.IsNull() ? myTimer->ElapsedTime() : 0.0; }
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);
127 //! Pause the process timeline.
128 Standard_EXPORT virtual void Pause();
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();
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; }
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);
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);
149 //! Update the own animation to specified position - should be overridden by sub-class.
150 virtual void update (const AIS_AnimationProgress& theProgress) { (void )theProgress; }
154 //! Defines animation state.
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
164 Handle(AIS_AnimationTimer) myTimer;
166 TCollection_AsciiString myName; //!< animation name
167 NCollection_Sequence<Handle(AIS_Animation)>
168 myAnimations; //!< sequence of child animations
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
177 #endif // _AIS_Animation_HeaderFile