DEFINE_STANDARD_HANDLE(AIS_Animation, Standard_Transient)
-//! Class represents single animation.
-//! It is defined with:
-//! - Start time on the timeline started from 0, in seconds
-//! - Duration, in seconds
-//! - virtual method Update() for handling an update
+//! Class represents a basic animation class.
+//! AIS_Animation can be used as:
+//!
+//! - Animation Implementor
+//! Sub-classes should override method AIS_Animation::update() to perform specific animation.
+//! AIS package provides limited number of such animation atoms - classes AIS_AnimationObject and AIS_AnimationCamera, which could be enough for defining a simple animation.
+//! In general case, application is expected defining own AIS_Animation sub-classes implementing application-specific animation logic
+//! (e.g. another interpolation or another kind of transformations - like color transition and others).
+//! The basic conception of AIS_Animation::update() is defining an exact scene state for the current presentation timestamp,
+//! providing a smooth and continuous animation well defined at any time step and in any direction.
+//! So that a time difference between two sequential drawn Viewer frames can vary from frame to frame without visual artifacts,
+//! increasing rendering framerate would not lead to animation being executed too fast
+//! and low framerate (on slow hardware) would not lead to animation played longer than defined duration.
+//! Hence, implementation should avoid usage of incremental step logic or should apply it very carefully.
+//!
+//! - Animation Container
+//! AIS_Animation (no sub-classing) can be used to aggregate a sequence of Animation items (children).
+//! Each children should be defined with its own duration and start time (presentation timestamp).
+//! It is possible defining collection of nested AIS_Animation items, so that within each container level
+//! children define start playback time relative to its holder.
+//!
+//! - Animation playback Controller
+//! It is suggested that application would define a single AIS_Animation instance (optional sub-classing) for controlling animation playback as whole.
+//! Such controller should be filled in by other AIS_Animation as children objects,
+//! and will be managed by application by calling StartTimer(), UpdateTimer() and IsStopped() methods.
+//!
+//! Note, that AIS_Animation::StartTimer() defines a timer calculating an elapsed time, not a multimedia timer executing Viewer updates at specific intervals!
+//! Application should avoid using implicit and immediate Viewer updates to ensure that AIS_Animation::UpdateTimer() is called before each redrawing of a Viewer content.
+//! Redrawing logic should be also managed at application level for managing a smooth animation
+//! (by defining a multimedia timer provided by used GUI framework executing updates at desired framerate, or as continuous redraws in loop).
class AIS_Animation : public Standard_Transient
{
DEFINE_STANDARD_RTTIEXT(AIS_Animation, Standard_Transient)
//! Start animation with internally defined timer instance.
//! Calls ::Start() internally.
+ //!
+ //! Note, that this method initializes a timer calculating an elapsed time (presentation timestamps within AIS_Animation::UpdateTimer()),
+ //! not a multimedia timer executing Viewer updates at specific intervals!
+ //! Viewer redrawing should be managed at application level, so that AIS_Animation::UpdateTimer() is called once right before each redrawing of a Viewer content.
+ //!
//! @param theStartPts starting timer position (presentation timestamp)
//! @param thePlaySpeed playback speed (1.0 means normal speed)
//! @param theToUpdate flag to update defined animations to specified start position
projects / occt.git / blobdiff