source: OGRE/trunk/ogrenew/OgreMain/include/OgreAnimationTrack.h @ 657

Revision 657, 8.7 KB checked in by mattausch, 19 years ago (diff)

added ogre dependencies and patched ogre sources

RevLine 
[657]1/*
2-----------------------------------------------------------------------------
3This source file is part of OGRE
4    (Object-oriented Graphics Rendering Engine)
5For the latest info, see http://www.ogre3d.org/
6
7Copyright (c) 2000-2005 The OGRE Team
8Also see acknowledgements in Readme.html
9
10This program is free software; you can redistribute it and/or modify it under
11the terms of the GNU Lesser General Public License as published by the Free Software
12Foundation; either version 2 of the License, or (at your option) any later
13version.
14
15This program is distributed in the hope that it will be useful, but WITHOUT
16ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS
17FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public License for more details.
18
19You should have received a copy of the GNU Lesser General Public License along with
20this program; if not, write to the Free Software Foundation, Inc., 59 Temple
21Place - Suite 330, Boston, MA 02111-1307, USA, or go to
22http://www.gnu.org/copyleft/lesser.txt.
23-----------------------------------------------------------------------------
24*/
25
26#ifndef __AnimationTrack_H__
27#define __AnimationTrack_H__
28
29#include "OgrePrerequisites.h"
30#include "OgreSimpleSpline.h"
31#include "OgreRotationalSpline.h"
32
33namespace Ogre
34{
35    /** A 'track' in an animation sequence, ie a sequence of keyframes which affect a
36        certain type of animable object.
37    @remarks
38        This class is intended as a base for more complete classes which will actually
39        animate specific types of object, e.g. a bone in a skeleton to affect
40        skeletal animation. An animation will likely include multiple tracks each of which
41        can be made up of many KeyFrame instances. Note that the use of tracks allows each animable
42        object to have it's own number of keyframes, i.e. you do not have to have the
43        maximum number of keyframes for all animable objects just to cope with the most
44        animated one.
45    @remarks
46        Since the most common animable object is a Node, there are options in this class for associating
47        the track with a Node which will receive keyframe updates automatically when the 'apply' method
48        is called.
49        @remarks
50                By default rotation is done using shortest-path algorithm.
51                It is possible to change this behaviour using
52                setUseShortestRotationPath() method.
53    */
54    class _OgreExport AnimationTrack
55    {
56    public:
57        /// Constructor
58        AnimationTrack(Animation* parent);
59        /// Constructor, associates with a Node
60        AnimationTrack(Animation* parent, Node* targetNode);
61
62        virtual ~AnimationTrack();
63
64        /** Returns the number of keyframes in this animation. */
65        unsigned short getNumKeyFrames(void) const;
66
67        /** Returns the KeyFrame at the specified index. */
68        KeyFrame* getKeyFrame(unsigned short index) const;
69
70        /** Gets the 2 KeyFrame objects which are active at the time given, and the blend value between them.
71        @remarks
72            At any point in time  in an animation, there are either 1 or 2 keyframes which are 'active',
73            1 if the time index is exactly on a keyframe, 2 at all other times i.e. the keyframe before
74            and the keyframe after.
75        @par
76            This method returns those keyframes given a time index, and also returns a parametric
77            value indicating the value of 't' representing where the time index falls between them.
78            E.g. if it returns 0, the time index is exactly on keyFrame1, if it returns 0.5 it is
79            half way between keyFrame1 and keyFrame2 etc.
80        @param timePos The time index in seconds.
81        @param keyFrame1 Pointer to a KeyFrame pointer which will receive the pointer to the
82            keyframe just before or at this time index.
83        @param keyFrame2 Pointer to a KeyFrame pointer which will receive the pointer to the
84            keyframe just after this time index.
85        @param firstKeyIndex Pointer to an unsigned short which, if supplied, will receive the
86            index of the 'from' keyframe incase the caller needs it.
87        @returns Parametric value indicating how far along the gap between the 2 keyframes the timePos
88            value is, e.g. 0.0 for exactly at 1, 0.25 for a quarter etc. By definition the range of this
89            value is:  0.0 <= returnValue < 1.0 .
90        */
91        Real getKeyFramesAtTime(Real timePos, KeyFrame** keyFrame1, KeyFrame** keyFrame2,
92            unsigned short* firstKeyIndex = 0) const;
93
94        /** Creates a new KeyFrame and adds it to this animation at the given time index.
95        @remarks
96            It is better to create KeyFrames in time order. Creating them out of order can result
97            in expensive reordering processing. Note that a KeyFrame at time index 0.0 is always created
98            for you, so you don't need to create this one, just access it using getKeyFrame(0);
99        @param timePos The time from which this KeyFrame will apply.
100        */
101        KeyFrame* createKeyFrame(Real timePos);
102
103        /** Removes a KeyFrame by it's index. */
104        void removeKeyFrame(unsigned short index);
105
106        /** Removes all the KeyFrames from this track. */
107        void removeAllKeyFrames(void);
108
109
110        /** Gets a KeyFrame object which contains the interpolated transforms at the time index specified.
111        @remarks
112            The KeyFrame objects held by this class are transformation snapshots at
113            discrete points in time. Normally however, you want to interpolate between these
114            keyframes to produce smooth movement, and this method allows you to do this easily.
115            In animation terminology this is called 'tweening'.
116        @param timeIndex The time (in relation to the whole animation sequence)
117        @returns A new keyframe object containing the interpolated transforms. Note that the
118            position and scaling transforms are linearly interpolated (lerp), whilst the rotation is
119            spherically linearly interpolated (slerp) for the most natural result.
120        */
121        KeyFrame getInterpolatedKeyFrame(Real timeIndex) const;
122
123        /** Applies an animation track at a certain position to the target node.
124        @remarks
125            When a track has bee associated with a target node, you can eaisly apply the animation
126            to the target by calling this method.
127        @param timePos The time position in the animation to apply.
128        @param weight The influence to give to this track, 1.0 for full influence, less to blend with
129          other animations.
130            @param scale The scale to apply to translations and scalings, useful for
131                        adapting an animation to a different size target.
132        */
133        void apply(Real timePos, Real weight = 1.0, bool accumulate = false,
134                        Real scale = 1.0f);
135
136        /** Returns a pointer to the associated Node object (if any). */
137        Node* getAssociatedNode(void) const;
138
139        /** Sets the associated Node object which will be automatically affected by calls to 'apply'. */
140        void setAssociatedNode(Node* node);
141
142        /** As the 'apply' method but applies to a specified Node instead of associated node. */
143        void applyToNode(Node* node, Real timePos, Real weight = 1.0,
144                        bool accumulate = false, Real scale = 1.0f);
145               
146                /** Sets the method of rotation calculation */
147                void setUseShortestRotationPath(bool useShortestPath);
148               
149                /** Gets the method of rotation calculation */
150                bool getUseShortestRotationPath() const;
151
152        /** Internal method used to tell the track that keyframe data has been
153            changed, which may cause it to rebuild some internal data. */
154        void _keyFrameDataChanged(void) const;
155
156                /** Method to determine if this track has any KeyFrames which are
157                        doing anything useful - can be used to determine if this track
158                        can be optimised out.
159                */
160                bool hasNonZeroKeyFrames(void) const;
161
162                /** Optimise the current track by removing any duplicate keyframes. */
163                void optimise(void);
164    protected:
165        typedef std::vector<KeyFrame*> KeyFrameList;
166        KeyFrameList mKeyFrames;
167        Real mMaxKeyFrameTime;
168        Animation* mParent;
169        Node* mTargetNode;
170
171        // Flag indicating we need to rebuild the splines next time
172        void buildInterpolationSplines(void) const;
173
174        // Prebuilt splines, must be mutable since lazy-update in const method
175        mutable bool mSplineBuildNeeded;
176        mutable SimpleSpline mPositionSpline;
177        mutable SimpleSpline mScaleSpline;
178        mutable RotationalSpline mRotationSpline;
179                /// Defines if rotation is done using shortest path
180                mutable bool mUseShortestRotationPath ;
181     
182
183    };
184}
185
186#endif
Note: See TracBrowser for help on using the repository browser.