0029936: Documentation - improve description of AIS_Animation class

src/AIS/AIS_Animation.hxx

@@ -31,11 +31,36 @@ struct AIS_AnimationProgress
 
 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)
@@ -101,6 +126,11 @@ public:
 
   //! 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