From 1f886fae1b87534faa142836f985b49bdd5b597e Mon Sep 17 00:00:00 2001 From: kgv Date: Sat, 7 Jul 2018 04:08:57 +0300 Subject: [PATCH] 0029936: Documentation - improve description of AIS_Animation class --- src/AIS/AIS_Animation.hxx | 40 ++++++++++++++++++++++++++++++++++----- 1 file changed, 35 insertions(+), 5 deletions(-) diff --git a/src/AIS/AIS_Animation.hxx b/src/AIS/AIS_Animation.hxx index 841278a53c..33d8693dbb 100644 --- a/src/AIS/AIS_Animation.hxx +++ b/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