source: OGRE/trunk/ogrenew/OgreMain/include/OgreAnimation.h @ 692

Revision 692, 15.0 KB checked in by mattausch, 18 years ago (diff)

adding ogre 1.2 and dependencies
Line 
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 __Animation_H__
27#define __Animation_H__
28
29#include "OgrePrerequisites.h"
30#include "OgreString.h"
31#include "OgreIteratorWrappers.h"
32#include "OgreAnimable.h"
33#include "OgreAnimationTrack.h"
34
35
36namespace Ogre {
37
38    /** An animation sequence.
39    @remarks
40        This class defines the interface for a sequence of animation, whether that
41        be animation of a mesh, a path along a spline, or possibly more than one
42        type of animation in one. An animation is made up of many 'tracks', which are
43        the more specific types of animation.
44    @par
45        You should not create these animations directly. They will be created via a parent
46        object which owns the animation, e.g. Skeleton.
47    */
48    class _OgreExport Animation
49    {
50
51    public:
52        /** The types of animation interpolation available. */
53        enum InterpolationMode
54        {
55            /** Values are interpolated along straight lines. */
56            IM_LINEAR,
57            /** Values are interpolated along a spline, resulting in smoother changes in direction. */
58            IM_SPLINE
59        };
60
61        /** The types of rotational interpolation available. */
62        enum RotationInterpolationMode
63        {
64            /** Values are interpolated linearly. This is faster but does not
65                necessarily give a completely accurate result.
66            */
67            RIM_LINEAR,
68            /** Values are interpolated spherically. This is more accurate but
69                has a higher cost.
70            */
71            RIM_SPHERICAL
72        };
73        /** You should not use this constructor directly, use the parent object such as Skeleton instead.
74        @param name The name of the animation, should be unique within it's parent (e.g. Skeleton)
75        @param length The length of the animation in seconds.
76        */
77        Animation(const String& name, Real length);
78        virtual ~Animation();
79
80        /** Gets the name of this animation. */
81        const String& getName(void) const;
82
83        /** Gets the total length of the animation. */
84        Real getLength(void) const;
85
86        /** Creates a NodeAnimationTrack for animating a Node.
87        @param handle Handle to give the track, used for accessing the track later.
88            Must be unique within this Animation.
89        */
90        NodeAnimationTrack* createNodeTrack(unsigned short handle);
91
92                /** Creates a NumericAnimationTrack for animating any numeric value.
93                @param handle Handle to give the track, used for accessing the track later.
94                Must be unique within this Animation.
95                */
96                NumericAnimationTrack* createNumericTrack(unsigned short handle);
97
98                /** Creates a VertexAnimationTrack for animating vertex position data.
99                @param handle Handle to give the track, used for accessing the track later.
100                Must be unique within this Animation, and is used to identify the target. For example
101                when applied to a Mesh, the handle must reference the index of the geometry being
102                modified; 0 for the shared geometry, and 1+ for SubMesh geometry with the same index-1.
103                @param animType Either morph or pose animation,
104                */
105                VertexAnimationTrack* createVertexTrack(unsigned short handle, VertexAnimationType animType);
106
107                /** Creates a new AnimationTrack automatically associated with a Node.
108        @remarks
109            This method creates a standard AnimationTrack, but also associates it with a
110            target Node which will receive all keyframe effects.
111        @param handle Numeric handle to give the track, used for accessing the track later.
112            Must be unique within this Animation.
113        @param node A pointer to the Node object which will be affected by this track
114        */
115        NodeAnimationTrack* createNodeTrack(unsigned short handle, Node* node);
116
117                /** Creates a NumericAnimationTrack and associates it with an animable.
118                @param handle Handle to give the track, used for accessing the track later.
119                @param anim Animable object link
120                Must be unique within this Animation.
121                */
122                NumericAnimationTrack* createNumericTrack(unsigned short handle,
123                        const AnimableValuePtr& anim);
124
125                /** Creates a VertexAnimationTrack and associates it with VertexData.
126                @param handle Handle to give the track, used for accessing the track later.
127                @param data VertexData object link
128                @param animType The animation type
129                Must be unique within this Animation.
130                */
131                VertexAnimationTrack* createVertexTrack(unsigned short handle,
132                        VertexData* data, VertexAnimationType animType);
133
134                /** Gets the number of NodeAnimationTrack objects contained in this animation. */
135        unsigned short getNumNodeTracks(void) const;
136
137        /** Gets a node track by it's handle. */
138        NodeAnimationTrack* getNodeTrack(unsigned short handle) const;
139
140                /** Does a track exist with the given handle? */
141                bool hasNodeTrack(unsigned short handle) const;
142
143                /** Gets the number of NumericAnimationTrack objects contained in this animation. */
144                unsigned short getNumNumericTracks(void) const;
145
146                /** Gets a numeric track by it's handle. */
147                NumericAnimationTrack* getNumericTrack(unsigned short handle) const;
148
149                /** Does a track exist with the given handle? */
150                bool hasNumericTrack(unsigned short handle) const;
151
152                /** Gets the number of VertexAnimationTrack objects contained in this animation. */
153                unsigned short getNumVertexTracks(void) const;
154
155                /** Gets a Vertex track by it's handle. */
156                VertexAnimationTrack* getVertexTrack(unsigned short handle) const;
157
158                /** Does a track exist with the given handle? */
159                bool hasVertexTrack(unsigned short handle) const;
160               
161                /** Destroys the node track with the given handle. */
162        void destroyNodeTrack(unsigned short handle);
163
164                /** Destroys the numeric track with the given handle. */
165                void destroyNumericTrack(unsigned short handle);
166
167                /** Destroys the Vertex track with the given handle. */
168                void destroyVertexTrack(unsigned short handle);
169
170                /** Removes and destroys all tracks making up this animation. */
171        void destroyAllTracks(void);
172
173                /** Removes and destroys all tracks making up this animation. */
174                void destroyAllNodeTracks(void);
175                /** Removes and destroys all tracks making up this animation. */
176                void destroyAllNumericTracks(void);
177                /** Removes and destroys all tracks making up this animation. */
178                void destroyAllVertexTracks(void);
179
180        /** Applies an animation given a specific time point and weight.
181        @remarks
182            Where you have associated animation tracks with objects, you can eaily apply
183            an animation to those objects by calling this method.
184        @param timePos The time position in the animation to apply.
185        @param weight The influence to give to this track, 1.0 for full influence, less to blend with
186          other animations.
187            @param scale The scale to apply to translations and scalings, useful for
188                        adapting an animation to a different size target.
189        */
190        void apply(Real timePos, Real weight = 1.0, bool accumulate = false,
191                        Real scale = 1.0f);
192
193        /** Applies all node tracks given a specific time point and weight to a given skeleton.
194        @remarks
195        Where you have associated animation tracks with Node objects, you can eaily apply
196        an animation to those nodes by calling this method.
197        @param timePos The time position in the animation to apply.
198        @param weight The influence to give to this track, 1.0 for full influence, less to blend with
199        other animations.
200            @param scale The scale to apply to translations and scalings, useful for
201                        adapting an animation to a different size target.
202        */
203        void apply(Skeleton* skeleton, Real timePos, Real weight = 1.0,
204                        bool accumulate = false, Real scale = 1.0f);
205
206                /** Applies all vertex tracks given a specific time point and weight to a given entity.
207                @remarks
208                @param entity The Entity to which this animation should be applied
209                @param timePos The time position in the animation to apply.
210                @param weight The weight at which the animation should be applied
211                        (only affects pose animation)
212                @param software Whether to populate the software morph vertex data
213                @param hardware Whether to populate the hardware morph vertex data
214                */
215                void apply(Entity* entity, Real timePos, Real weight, bool software,
216                        bool hardware);
217
218        /** Tells the animation how to interpolate between keyframes.
219        @remarks
220            By default, animations normally interpolate linearly between keyframes. This is
221            fast, but when animations include quick changes in direction it can look a little
222            unnatural because directions change instantly at keyframes. An alternative is to
223            tell the animation to interpolate along a spline, which is more expensive in terms
224            of calculation time, but looks smoother because major changes in direction are
225            distributed around the keyframes rather than just at the keyframe.
226        @par
227            You can also change the default animation behaviour by calling
228            Animation::setDefaultInterpolationMode.
229        */
230        void setInterpolationMode(InterpolationMode im);
231
232        /** Gets the current interpolation mode of this animation.
233        @remarks
234            See setInterpolationMode for more info.
235        */
236        InterpolationMode getInterpolationMode(void) const;
237        /** Tells the animation how to interpolate rotations.
238        @remarks
239            By default, animations interpolate lieanrly between rotations. This
240            is fast but not necessarily completely accurate. If you want more
241            accurate interpolation, use spherical interpolation, but be aware
242            that it will incur a higher cost.
243        @par
244            You can also change the default rotation behaviour by calling
245            Animation::setDefaultRotationInterpolationMode.
246        */
247        void setRotationInterpolationMode(RotationInterpolationMode im);
248
249        /** Gets the current rotation interpolation mode of this animation.
250        @remarks
251            See setRotationInterpolationMode for more info.
252        */
253        RotationInterpolationMode getRotationInterpolationMode(void) const;
254
255        // Methods for setting the defaults
256        /** Sets the default animation interpolation mode.
257        @remarks
258            Every animation created after this option is set will have the new interpolation
259            mode specified. You can also change the mode per animation by calling the
260            setInterpolationMode method on the instance in question.
261        */
262        static void setDefaultInterpolationMode(InterpolationMode im);
263
264        /** Gets the default interpolation mode for all animations. */
265        static InterpolationMode getDefaultInterpolationMode(void);
266
267        /** Sets the default rotation interpolation mode.
268        @remarks
269            Every animation created after this option is set will have the new interpolation
270            mode specified. You can also change the mode per animation by calling the
271            setInterpolationMode method on the instance in question.
272        */
273        static void setDefaultRotationInterpolationMode(RotationInterpolationMode im);
274
275        /** Gets the default rotation interpolation mode for all animations. */
276        static RotationInterpolationMode getDefaultRotationInterpolationMode(void);
277
278        typedef std::map<unsigned short, NodeAnimationTrack*> NodeTrackList;
279        typedef ConstMapIterator<NodeTrackList> NodeTrackIterator;
280
281                typedef std::map<unsigned short, NumericAnimationTrack*> NumericTrackList;
282                typedef ConstMapIterator<NumericTrackList> NumericTrackIterator;
283
284                typedef std::map<unsigned short, VertexAnimationTrack*> VertexTrackList;
285                typedef ConstMapIterator<VertexTrackList> VertexTrackIterator;
286
287                /// Fast access to NON-UPDATEABLE node track list
288        const NodeTrackList& _getNodeTrackList(void) const;
289
290        /// Get non-updateable iterator over node tracks
291        NodeTrackIterator getNodeTrackIterator(void) const
292        { return NodeTrackIterator(mNodeTrackList.begin(), mNodeTrackList.end()); }
293       
294                /// Fast access to NON-UPDATEABLE numeric track list
295                const NumericTrackList& _getNumericTrackList(void) const;
296
297                /// Get non-updateable iterator over node tracks
298                NumericTrackIterator getNumericTrackIterator(void) const
299                { return NumericTrackIterator(mNumericTrackList.begin(), mNumericTrackList.end()); }
300
301                /// Fast access to NON-UPDATEABLE Vertex track list
302                const VertexTrackList& _getVertexTrackList(void) const;
303
304                /// Get non-updateable iterator over node tracks
305                VertexTrackIterator getVertexTrackIterator(void) const
306                { return VertexTrackIterator(mVertexTrackList.begin(), mVertexTrackList.end()); }
307
308                /** Optimise an animation by removing unnecessary tracks and keyframes.
309                @remarks
310                        When you export an animation, it is possible that certain tracks
311                        have been keyfamed but actually don't include anything useful - the
312                        keyframes include no transformation. These tracks can be completely
313                        eliminated from the animation and thus speed up the animation.
314                        In addition, if several keyframes in a row have the same value,
315                        then they are just adding overhead and can be removed.
316                */
317                void optimise(void);
318               
319
320
321    protected:
322        /// Node tracks, indexed by handle
323        NodeTrackList mNodeTrackList;
324                /// Numeric tracks, indexed by handle
325                NumericTrackList mNumericTrackList;
326                /// Vertex tracks, indexed by handle
327                VertexTrackList mVertexTrackList;
328        String mName;
329
330        Real mLength;
331
332        InterpolationMode mInterpolationMode;
333        RotationInterpolationMode mRotationInterpolationMode;
334
335        static InterpolationMode msDefaultInterpolationMode;
336        static RotationInterpolationMode msDefaultRotationInterpolationMode;
337
338                void optimiseNodeTracks(void);
339                void optimiseVertexTracks(void);
340
341       
342    };
343
344
345}
346
347
348#endif
349
Note: See TracBrowser for help on using the repository browser.