0031687: Draw Harness, ViewerTest - extend command vrenderparams with option updating...
[occt.git] / src / AIS / AIS_Animation.hxx
CommitLineData
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.
23struct 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
32DEFINE_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 64class AIS_Animation : public Standard_Transient
65{
66 DEFINE_STANDARD_RTTIEXT(AIS_Animation, Standard_Transient)
67public:
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
78public:
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
125public:
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
150public:
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
173protected:
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
182protected:
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
192protected:
193
98e6c6d1 194 Handle(Media_Timer) myTimer;
1beb58d7 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