#include <keyFrameInterpolator.h>
A keyFrame Catmull-Rom Frame interpolator. More...
A keyFrame Catmull-Rom Frame interpolator.
QGLViewer/keyFrameInterpolator.h
A KeyFrameInterpolator holds keyFrames (that define a path) and a pointer to a Frame of your application (which will be interpolated). When the user startInterpolation(), the KeyFrameInterpolator regularly updates the frame() position and orientation along the path.
Here is a typical utilization example (see also the keyFrames example):
The keyFrames are defined by a Frame and a time, expressed in seconds. The Frame can be provided as a const reference or as a pointer to a Frame (see the addKeyFrame() methods). In the latter case, the path will automatically be updated when the Frame is modified (using the Frame::modified() signal).
The time has to be monotonously increasing over keyFrames. When interpolationSpeed() equals 1.0 (default value), these times correspond to actual user's seconds during interpolation (provided that your main loop is fast enough). The interpolation is then real-time: the keyFrames will be reached at their keyFrameTime().
When the user startInterpolation(), a timer is started which will update the frame()'s position and orientation every interpolationPeriod() milliseconds. This update increases the interpolationTime() by interpolationPeriod() * interpolationSpeed() milliseconds.
Note that this mechanism ensures that the number of interpolation steps is constant and equal to the total path duration() divided by the interpolationPeriod() * interpolationSpeed(). This is especially useful for benchmarking or movie creation (constant number of snapshots).
During the interpolation, the KeyFrameInterpolator emits an interpolated() signal, which will usually be connected to the QGLViewer::update() slot. The interpolation is stopped when interpolationTime() is greater than the lastTime() (unless loopInterpolation() is true
) and the endReached() signal is then emitted.
Note that a Camera has Camera::keyFrameInterpolator(), that can be used to drive the Camera along a path, or to restore a saved position (a path made of a single keyFrame). Press Alt+Fx to define a new keyFrame for path x. Pressing Fx plays/pauses path interpolation. See QGLViewer::pathKey() and the keyboard page for details.
This code defines a KeyFrameInterpolator, and displays the positions that will be followed by the frame() along the path:
You may want to temporally disconnect the kfi
interpolated() signal from the QGLViewer::update() slot before calling this code.
Public Member Functions | |
KeyFrameInterpolator (Frame *fr=nullptr) | |
Creates a KeyFrameInterpolator, with frame as associated frame(). More... | |
virtual | ~KeyFrameInterpolator () |
Virtual destructor. More... | |
Signals | |
void | interpolated () |
This signal is emitted whenever the frame() state is interpolated. More... | |
void | endReached () |
This signal is emitted when the interpolation reaches the first (when interpolationSpeed() is negative) or the last keyFrame. More... | |
XML representation | |
virtual QDomElement | domElement (const QString &name, QDomDocument &document) const |
Returns an XML QDomElement that represents the KeyFrameInterpolator. More... | |
virtual void | initFromDOMElement (const QDomElement &element) |
Restores the KeyFrameInterpolator state from a QDomElement created by domElement(). More... | |
Associated Frame | |
Frame * | frame () const |
Returns the associated Frame and that is interpolated by the KeyFrameInterpolator. More... | |
void | setFrame (Frame *const frame) |
Sets the frame() associated to the KeyFrameInterpolator. More... | |
Path parameters | |
Frame | keyFrame (int index) const |
Returns the Frame associated with the keyFrame at index index . More... | |
qreal | keyFrameTime (int index) const |
Returns the time corresponding to the index keyFrame. More... | |
int | numberOfKeyFrames () const |
Returns the number of keyFrames used by the interpolation. More... | |
qreal | duration () const |
Returns the duration of the KeyFrameInterpolator path, expressed in seconds. More... | |
qreal | firstTime () const |
Returns the time corresponding to the first keyFrame, expressed in seconds. More... | |
qreal | lastTime () const |
Returns the time corresponding to the last keyFrame, expressed in seconds. More... | |
Interpolation parameters | |
qreal | interpolationTime () const |
Returns the current interpolation time (in seconds) along the KeyFrameInterpolator path. More... | |
qreal | interpolationSpeed () const |
Returns the current interpolation speed. More... | |
int | interpolationPeriod () const |
Returns the current interpolation period, expressed in milliseconds. More... | |
bool | loopInterpolation () const |
Returns true when the interpolation is played in an infinite loop. More... | |
bool | closedPath () const |
Whether or not (default) the path defined by the keyFrames is a closed loop. More... | |
void | setInterpolationTime (qreal time) |
Sets the interpolationTime(). More... | |
void | setInterpolationSpeed (qreal speed) |
Sets the interpolationSpeed(). More... | |
void | setInterpolationPeriod (int period) |
Sets the interpolationPeriod(). More... | |
void | setLoopInterpolation (bool loop=true) |
Sets the loopInterpolation() value. More... | |
void | setClosedPath (bool closed=true) |
Sets the closedPath() value. More... | |
Interpolation | |
bool | interpolationIsStarted () const |
Returns true when the interpolation is being performed. More... | |
void | startInterpolation (int period=-1) |
Starts the interpolation process. More... | |
void | stopInterpolation () |
Stops an interpolation started with startInterpolation(). More... | |
void | resetInterpolation () |
Stops the interpolation and resets interpolationTime() to the firstTime(). More... | |
void | toggleInterpolation () |
Calls startInterpolation() or stopInterpolation(), depending on interpolationIsStarted(). More... | |
virtual void | interpolateAtTime (qreal time) |
Interpolate frame() at time time (expressed in seconds). More... | |
Path drawing | |
virtual void | drawPath (int mask=1, int nbFrames=6, qreal scale=1.0) |
Draws the path used to interpolate the frame(). More... | |
Path creation | |
void | addKeyFrame (const Frame &frame) |
Appends a new keyFrame to the path. More... | |
void | addKeyFrame (const Frame &frame, qreal time) |
Appends a new keyFrame to the path, with its associated time (in seconds). More... | |
void | addKeyFrame (const Frame *const frame) |
Appends a new keyFrame to the path. More... | |
void | addKeyFrame (const Frame *const frame, qreal time) |
Appends a new keyFrame to the path, with its associated time (in seconds). More... | |
void | deletePath () |
Removes all keyFrames from the path. More... | |
KeyFrameInterpolator::KeyFrameInterpolator | ( | Frame * | frame = nullptr | ) |
Creates a KeyFrameInterpolator, with frame
as associated frame().
The frame() can be set or changed using setFrame().
interpolationTime(), interpolationSpeed() and interpolationPeriod() are set to their default values.
|
virtual |
Virtual destructor.
Clears the keyFrame path.
|
slot |
Appends a new keyFrame to the path.
Same as addKeyFrame(const Frame& frame, qreal), except that the keyFrameTime() is automatically set to previous keyFrameTime() plus one second (or 0.0 if there is no previous keyFrame).
|
slot |
Appends a new keyFrame to the path, with its associated time
(in seconds).
The path will use the current frame
state. If you want the path to change when frame
is modified, you need to pass a pointer to the Frame instead (see addKeyFrame(const Frame*, qreal)).
The keyFrameTime() have to be monotonously increasing over keyFrames.
|
slot |
Appends a new keyFrame to the path.
Same as addKeyFrame(const Frame* frame, qreal), except that the keyFrameTime() is set to the previous keyFrameTime() plus one second (or 0.0 if there is no previous keyFrame).
|
slot |
Appends a new keyFrame to the path, with its associated time
(in seconds).
The keyFrame is given as a pointer to a Frame, which will be connected to the KeyFrameInterpolator: when frame
is modified, the KeyFrameInterpolator path is updated accordingly. This allows for dynamic paths, where keyFrame can be edited, even during the interpolation. See the keyFrames example for an illustration.
nullptr
frame
pointers are silently ignored. The keyFrameTime() has to be monotonously increasing over keyFrames.
Use addKeyFrame(const Frame&, qreal) to add keyFrame by values.
|
inline |
Whether or not (default) the path defined by the keyFrames is a closed loop.
When true
, the last and the first KeyFrame are linked by a new spline segment.
Use setLoopInterpolation() to create a continuous animation over the entire path.
|
slot |
Removes all keyFrames from the path.
The numberOfKeyFrames() is set to 0.
|
virtual |
Returns an XML QDomElement
that represents the KeyFrameInterpolator.
The resulting QDomElement holds the KeyFrameInterpolator parameters as well as the path keyFrames (if the keyFrame is defined by a pointer to a Frame, use its current value).
name
is the name of the QDomElement tag. doc
is the QDomDocument
factory used to create QDomElement.
Use initFromDOMElement() to restore the ManipulatedFrame state from the resulting QDomElement.
See Vec::domElement() for a complete example. See also Quaternion::domElement(), Camera::domElement()...
Note that the Camera::keyFrameInterpolator() are automatically saved by QGLViewer::saveStateToFile() when a QGLViewer is closed.
|
virtual |
Draws the path used to interpolate the frame().
mask
controls what is drawn: if (mask & 1) (default), the position path is drawn. If (mask & 2), a camera representation is regularly drawn and if (mask & 4), an oriented axis is regularly drawn. Examples:
In the case where camera or axis is drawn, nbFrames
controls the number of objects (axis or camera) drawn between two successive keyFrames. When nbFrames=1
, only the path KeyFrames are drawn. nbFrames=2
also draws the intermediate orientation, etc. The maximum value is 30. nbFrames
should divide 30 so that an object is drawn for each KeyFrame. Default value is 6.
scale
(default=1.0) controls the scaling of the camera and axis drawing. A value of QGLViewer::sceneRadius() should give good results.
See the keyFrames example for an illustration.
The color of the path is the current glColor()
.
qreal KeyFrameInterpolator::duration | ( | ) | const |
Returns the duration of the KeyFrameInterpolator path, expressed in seconds.
Simply corresponds to lastTime() - firstTime(). Returns 0.0 if the path has less than 2 keyFrames. See also keyFrameTime().
|
signal |
This signal is emitted when the interpolation reaches the first (when interpolationSpeed() is negative) or the last keyFrame.
When loopInterpolation() is true
, interpolationTime() is reset and the interpolation continues. It otherwise stops.
qreal KeyFrameInterpolator::firstTime | ( | ) | const |
Returns the time corresponding to the first keyFrame, expressed in seconds.
Returns 0.0 if the path is empty. See also lastTime(), duration() and keyFrameTime().
|
inline |
Returns the associated Frame and that is interpolated by the KeyFrameInterpolator.
When interpolationIsStarted(), this Frame's position and orientation will regularly be updated by a timer, so that they follow the KeyFrameInterpolator path.
Set using setFrame() or with the KeyFrameInterpolator constructor.
|
virtual |
Restores the KeyFrameInterpolator state from a QDomElement
created by domElement().
Note that the frame() pointer is not included in the domElement(): you need to setFrame() after this method to attach a Frame to the KeyFrameInterpolator.
See Vec::initFromDOMElement() for a complete code example.
See also Camera::initFromDOMElement() and Frame::initFromDOMElement().
|
virtualslot |
Interpolate frame() at time time
(expressed in seconds).
interpolationTime() is set to time
and frame() is set accordingly.
If you simply want to change interpolationTime() but not the frame() state, use setInterpolationTime() instead.
Emits the interpolated() signal and makes the frame() emit the Frame::interpolated() signal.
|
signal |
This signal is emitted whenever the frame() state is interpolated.
The emission of this signal triggers the synchronous emission of the frame() Frame::interpolated() signal, which may also be useful.
This signal should especially be connected to your QGLViewer::update() slot, so that the display is updated after every update of the KeyFrameInterpolator frame():
Use the QGLViewer::QGLViewerPool() to connect the signal to all the viewers.
Note that the QGLViewer::camera() Camera::keyFrameInterpolator() created using QGLViewer::pathKey() have their interpolated() signals automatically connected to the QGLViewer::update() slot.
|
inline |
Returns true
when the interpolation is being performed.
Use startInterpolation(), stopInterpolation() or toggleInterpolation() to modify this state.
|
inline |
Returns the current interpolation period, expressed in milliseconds.
The update of the frame() state will be done by a timer at this period when interpolationIsStarted().
This period (multiplied by interpolationSpeed()) is added to the interpolationTime() at each update, and the frame() state is modified accordingly (see interpolateAtTime()). Default value is 40 milliseconds.
|
inline |
Returns the current interpolation speed.
Default value is 1.0, which means keyFrameTime() will be matched during the interpolation (provided that your main loop is fast enough).
A negative value will result in a reverse interpolation of the keyFrames. See also interpolationPeriod().
|
inline |
Returns the current interpolation time (in seconds) along the KeyFrameInterpolator path.
This time is regularly updated when interpolationIsStarted(). Can be set directly with setInterpolationTime() or interpolateAtTime().
Frame KeyFrameInterpolator::keyFrame | ( | int | index | ) | const |
Returns the Frame associated with the keyFrame at index index
.
See also keyFrameTime(). index
has to be in the range 0..numberOfKeyFrames()-1.
qreal KeyFrameInterpolator::keyFrameTime | ( | int | index | ) | const |
Returns the time corresponding to the index
keyFrame.
See also keyFrame(). index
has to be in the range 0..numberOfKeyFrames()-1.
qreal KeyFrameInterpolator::lastTime | ( | ) | const |
Returns the time corresponding to the last keyFrame, expressed in seconds.
Returns 0.0 if the path is empty. See also firstTime(), duration() and keyFrameTime().
|
inline |
Returns true
when the interpolation is played in an infinite loop.
When false
(default), the interpolation stops when interpolationTime() reaches firstTime() (with negative interpolationSpeed()) or lastTime().
interpolationTime() is otherwise reset to firstTime() (+ interpolationTime() - lastTime()) (and inversely for negative interpolationSpeed()) and interpolation continues.
In both cases, the endReached() signal is emitted.
|
inline |
Returns the number of keyFrames used by the interpolation.
Use addKeyFrame() to add new keyFrames.
|
slot |
Stops the interpolation and resets interpolationTime() to the firstTime().
If desired, call interpolateAtTime() after this method to actually move the frame() to firstTime().
|
inlineslot |
Sets the closedPath() value.
|
slot |
Sets the frame() associated to the KeyFrameInterpolator.
|
inlineslot |
Sets the interpolationPeriod().
|
inlineslot |
Sets the interpolationSpeed().
Negative or null values are allowed.
|
inlineslot |
Sets the interpolationTime().
|
inlineslot |
Sets the loopInterpolation() value.
|
slot |
Starts the interpolation process.
A timer is started with an interpolationPeriod() period that updates the frame()'s position and orientation. interpolationIsStarted() will return true
until stopInterpolation() or toggleInterpolation() is called.
If period
is positive, it is set as the new interpolationPeriod(). The previous interpolationPeriod() is used otherwise (default).
If interpolationTime() is larger than lastTime(), interpolationTime() is reset to firstTime() before interpolation starts (and inversely for negative interpolationSpeed()).
Use setInterpolationTime() before calling this method to change the starting interpolationTime().
See the keyFrames example for an illustration.
You may also be interested in QGLViewer::animate() and QGLViewer::startAnimation().
|
slot |
Stops an interpolation started with startInterpolation().
|
inlineslot |
Calls startInterpolation() or stopInterpolation(), depending on interpolationIsStarted().