1beb58d7 |
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 | |
1f886fae |
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). |
1beb58d7 |
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. |
76 | const TCollection_AsciiString& Name() const { return myName; } |
77 | |
78 | public: |
79 | |
80 | //! @return start time of the animation in the timeline |
81 | Standard_Real StartPts() const { return myPtsStart; } |
82 | |
83 | //! Sets time limits for animation in the animation timeline |
84 | void SetStartPts (const Standard_Real thePtsStart) { myPtsStart = thePtsStart; } |
85 | |
86 | //! @return duration of the animation in the timeline |
87 | 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. |
93 | Standard_Boolean HasOwnDuration() const { return myOwnDuration > 0.0; } |
94 | |
95 | //! @return own duration of the animation in the timeline |
96 | Standard_Real OwnDuration() const { return myOwnDuration; } |
97 | |
98 | //! Defines duration of the animation. |
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. |
123 | 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. |
1f886fae |
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 | //! |
bf7b2ceb |
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 |
1beb58d7 |
138 | Standard_EXPORT virtual void StartTimer (const Standard_Real theStartPts, |
139 | const Standard_Real thePlaySpeed, |
bf7b2ceb |
140 | const Standard_Boolean theToUpdate, |
141 | const Standard_Boolean theToStopTimer = Standard_False); |
1beb58d7 |
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. |
148 | Standard_Real ElapsedTime() const { return !myTimer.IsNull() ? myTimer->ElapsedTime() : 0.0; } |
149 | |
150 | public: |
151 | |
152 | //! Start animation. This method changes status of the animation to Started. |
153 | //! This status defines whether animation is to be performed in the timeline or not. |
154 | //! @param theToUpdate call Update() method |
155 | Standard_EXPORT virtual void Start (const Standard_Boolean theToUpdate); |
156 | |
157 | //! Pause the process timeline. |
158 | Standard_EXPORT virtual void Pause(); |
159 | |
160 | //! Stop animation. This method changed status of the animation to Stopped. |
161 | //! This status shows that animation will not be performed in the timeline or it is finished. |
162 | Standard_EXPORT virtual void Stop(); |
163 | |
164 | //! Check if animation is to be performed in the animation timeline. |
165 | //! @return True if it is stopped of finished. |
166 | bool IsStopped() { return myState != AnimationState_Started; } |
167 | |
168 | //! Update single frame of animation, update timer state |
169 | //! @param thePts [in] the time moment within [0; Duration()] |
170 | //! @return True if timeline is in progress |
171 | Standard_EXPORT virtual Standard_Boolean Update (const Standard_Real thePts); |
172 | |
173 | protected: |
174 | |
175 | //! Process one step of the animation according to the input time progress, including all children. |
176 | //! Calls also ::update() to update own animation. |
177 | Standard_EXPORT virtual void updateWithChildren (const AIS_AnimationProgress& thePosition); |
178 | |
179 | //! Update the own animation to specified position - should be overridden by sub-class. |
180 | virtual void update (const AIS_AnimationProgress& theProgress) { (void )theProgress; } |
181 | |
182 | protected: |
183 | |
184 | //! Defines animation state. |
185 | enum AnimationState |
186 | { |
187 | AnimationState_Started, //!< animation is in progress |
188 | AnimationState_Stopped, //!< animation is finished, force stopped or not started |
189 | AnimationState_Paused //!< animation is paused and can be started from the pause moment |
190 | }; |
191 | |
192 | protected: |
193 | |
194 | Handle(AIS_AnimationTimer) myTimer; |
195 | |
196 | TCollection_AsciiString myName; //!< animation name |
197 | NCollection_Sequence<Handle(AIS_Animation)> |
198 | myAnimations; //!< sequence of child animations |
199 | |
200 | AnimationState myState; //!< animation state - started, stopped of paused |
201 | Standard_Real myPtsStart; //!< time of start in the timeline |
202 | Standard_Real myOwnDuration; //!< duration of animation excluding children |
203 | Standard_Real myChildrenDuration; //!< duration of animation including children |
204 | |
205 | }; |
206 | |
207 | #endif // _AIS_Animation_HeaderFile |