[5] | 1 | /* |
---|
| 2 | ----------------------------------------------------------------------------- |
---|
| 3 | This source file is part of OGRE |
---|
| 4 | (Object-oriented Graphics Rendering Engine) |
---|
| 5 | For the latest info, see http://www.ogre3d.org/ |
---|
| 6 | |
---|
| 7 | Copyright (c) 2000-2006 Torus Knot Software Ltd |
---|
| 8 | Also see acknowledgements in Readme.html |
---|
| 9 | |
---|
| 10 | This program is free software; you can redistribute it and/or modify it under |
---|
| 11 | the terms of the GNU Lesser General Public License as published by the Free Software |
---|
| 12 | Foundation; either version 2 of the License, or (at your option) any later |
---|
| 13 | version. |
---|
| 14 | |
---|
| 15 | This program is distributed in the hope that it will be useful, but WITHOUT |
---|
| 16 | ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS |
---|
| 17 | FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public License for more details. |
---|
| 18 | |
---|
| 19 | You should have received a copy of the GNU Lesser General Public License along with |
---|
| 20 | this program; if not, write to the Free Software Foundation, Inc., 59 Temple |
---|
| 21 | Place - Suite 330, Boston, MA 02111-1307, USA, or go to |
---|
| 22 | http://www.gnu.org/copyleft/lesser.txt. |
---|
| 23 | |
---|
| 24 | You may alternatively use this source under the terms of a specific version of |
---|
| 25 | the OGRE Unrestricted License provided you have obtained such a license from |
---|
| 26 | Torus Knot Software Ltd. |
---|
| 27 | ----------------------------------------------------------------------------- |
---|
| 28 | */ |
---|
| 29 | |
---|
| 30 | #ifndef __Animation_H__ |
---|
| 31 | #define __Animation_H__ |
---|
| 32 | |
---|
| 33 | #include "OgrePrerequisites.h" |
---|
| 34 | #include "OgreString.h" |
---|
| 35 | #include "OgreIteratorWrappers.h" |
---|
| 36 | #include "OgreAnimable.h" |
---|
| 37 | #include "OgreAnimationTrack.h" |
---|
| 38 | |
---|
| 39 | |
---|
| 40 | namespace Ogre { |
---|
| 41 | |
---|
| 42 | /** An animation sequence. |
---|
| 43 | @remarks |
---|
| 44 | This class defines the interface for a sequence of animation, whether that |
---|
| 45 | be animation of a mesh, a path along a spline, or possibly more than one |
---|
| 46 | type of animation in one. An animation is made up of many 'tracks', which are |
---|
| 47 | the more specific types of animation. |
---|
| 48 | @par |
---|
| 49 | You should not create these animations directly. They will be created via a parent |
---|
| 50 | object which owns the animation, e.g. Skeleton. |
---|
| 51 | */ |
---|
| 52 | class _OgreExport Animation |
---|
| 53 | { |
---|
| 54 | |
---|
| 55 | public: |
---|
| 56 | /** The types of animation interpolation available. */ |
---|
| 57 | enum InterpolationMode |
---|
| 58 | { |
---|
| 59 | /** Values are interpolated along straight lines. */ |
---|
| 60 | IM_LINEAR, |
---|
| 61 | /** Values are interpolated along a spline, resulting in smoother changes in direction. */ |
---|
| 62 | IM_SPLINE |
---|
| 63 | }; |
---|
| 64 | |
---|
| 65 | /** The types of rotational interpolation available. */ |
---|
| 66 | enum RotationInterpolationMode |
---|
| 67 | { |
---|
| 68 | /** Values are interpolated linearly. This is faster but does not |
---|
| 69 | necessarily give a completely accurate result. |
---|
| 70 | */ |
---|
| 71 | RIM_LINEAR, |
---|
| 72 | /** Values are interpolated spherically. This is more accurate but |
---|
| 73 | has a higher cost. |
---|
| 74 | */ |
---|
| 75 | RIM_SPHERICAL |
---|
| 76 | }; |
---|
| 77 | /** You should not use this constructor directly, use the parent object such as Skeleton instead. |
---|
| 78 | @param name The name of the animation, should be unique within it's parent (e.g. Skeleton) |
---|
| 79 | @param length The length of the animation in seconds. |
---|
| 80 | */ |
---|
| 81 | Animation(const String& name, Real length); |
---|
| 82 | virtual ~Animation(); |
---|
| 83 | |
---|
| 84 | /** Gets the name of this animation. */ |
---|
| 85 | const String& getName(void) const; |
---|
| 86 | |
---|
| 87 | /** Gets the total length of the animation. */ |
---|
| 88 | Real getLength(void) const; |
---|
| 89 | |
---|
| 90 | /** Creates a NodeAnimationTrack for animating a Node. |
---|
| 91 | @param handle Handle to give the track, used for accessing the track later. |
---|
| 92 | Must be unique within this Animation. |
---|
| 93 | */ |
---|
| 94 | NodeAnimationTrack* createNodeTrack(unsigned short handle); |
---|
| 95 | |
---|
| 96 | /** Creates a NumericAnimationTrack for animating any numeric value. |
---|
| 97 | @param handle Handle to give the track, used for accessing the track later. |
---|
| 98 | Must be unique within this Animation. |
---|
| 99 | */ |
---|
| 100 | NumericAnimationTrack* createNumericTrack(unsigned short handle); |
---|
| 101 | |
---|
| 102 | /** Creates a VertexAnimationTrack for animating vertex position data. |
---|
| 103 | @param handle Handle to give the track, used for accessing the track later. |
---|
| 104 | Must be unique within this Animation, and is used to identify the target. For example |
---|
| 105 | when applied to a Mesh, the handle must reference the index of the geometry being |
---|
| 106 | modified; 0 for the shared geometry, and 1+ for SubMesh geometry with the same index-1. |
---|
| 107 | @param animType Either morph or pose animation, |
---|
| 108 | */ |
---|
| 109 | VertexAnimationTrack* createVertexTrack(unsigned short handle, VertexAnimationType animType); |
---|
| 110 | |
---|
| 111 | /** Creates a new AnimationTrack automatically associated with a Node. |
---|
| 112 | @remarks |
---|
| 113 | This method creates a standard AnimationTrack, but also associates it with a |
---|
| 114 | target Node which will receive all keyframe effects. |
---|
| 115 | @param handle Numeric handle to give the track, used for accessing the track later. |
---|
| 116 | Must be unique within this Animation. |
---|
| 117 | @param node A pointer to the Node object which will be affected by this track |
---|
| 118 | */ |
---|
| 119 | NodeAnimationTrack* createNodeTrack(unsigned short handle, Node* node); |
---|
| 120 | |
---|
| 121 | /** Creates a NumericAnimationTrack and associates it with an animable. |
---|
| 122 | @param handle Handle to give the track, used for accessing the track later. |
---|
| 123 | @param anim Animable object link |
---|
| 124 | Must be unique within this Animation. |
---|
| 125 | */ |
---|
| 126 | NumericAnimationTrack* createNumericTrack(unsigned short handle, |
---|
| 127 | const AnimableValuePtr& anim); |
---|
| 128 | |
---|
| 129 | /** Creates a VertexAnimationTrack and associates it with VertexData. |
---|
| 130 | @param handle Handle to give the track, used for accessing the track later. |
---|
| 131 | @param data VertexData object link |
---|
| 132 | @param animType The animation type |
---|
| 133 | Must be unique within this Animation. |
---|
| 134 | */ |
---|
| 135 | VertexAnimationTrack* createVertexTrack(unsigned short handle, |
---|
| 136 | VertexData* data, VertexAnimationType animType); |
---|
| 137 | |
---|
| 138 | /** Gets the number of NodeAnimationTrack objects contained in this animation. */ |
---|
| 139 | unsigned short getNumNodeTracks(void) const; |
---|
| 140 | |
---|
| 141 | /** Gets a node track by it's handle. */ |
---|
| 142 | NodeAnimationTrack* getNodeTrack(unsigned short handle) const; |
---|
| 143 | |
---|
| 144 | /** Does a track exist with the given handle? */ |
---|
| 145 | bool hasNodeTrack(unsigned short handle) const; |
---|
| 146 | |
---|
| 147 | /** Gets the number of NumericAnimationTrack objects contained in this animation. */ |
---|
| 148 | unsigned short getNumNumericTracks(void) const; |
---|
| 149 | |
---|
| 150 | /** Gets a numeric track by it's handle. */ |
---|
| 151 | NumericAnimationTrack* getNumericTrack(unsigned short handle) const; |
---|
| 152 | |
---|
| 153 | /** Does a track exist with the given handle? */ |
---|
| 154 | bool hasNumericTrack(unsigned short handle) const; |
---|
| 155 | |
---|
| 156 | /** Gets the number of VertexAnimationTrack objects contained in this animation. */ |
---|
| 157 | unsigned short getNumVertexTracks(void) const; |
---|
| 158 | |
---|
| 159 | /** Gets a Vertex track by it's handle. */ |
---|
| 160 | VertexAnimationTrack* getVertexTrack(unsigned short handle) const; |
---|
| 161 | |
---|
| 162 | /** Does a track exist with the given handle? */ |
---|
| 163 | bool hasVertexTrack(unsigned short handle) const; |
---|
| 164 | |
---|
| 165 | /** Destroys the node track with the given handle. */ |
---|
| 166 | void destroyNodeTrack(unsigned short handle); |
---|
| 167 | |
---|
| 168 | /** Destroys the numeric track with the given handle. */ |
---|
| 169 | void destroyNumericTrack(unsigned short handle); |
---|
| 170 | |
---|
| 171 | /** Destroys the Vertex track with the given handle. */ |
---|
| 172 | void destroyVertexTrack(unsigned short handle); |
---|
| 173 | |
---|
| 174 | /** Removes and destroys all tracks making up this animation. */ |
---|
| 175 | void destroyAllTracks(void); |
---|
| 176 | |
---|
| 177 | /** Removes and destroys all tracks making up this animation. */ |
---|
| 178 | void destroyAllNodeTracks(void); |
---|
| 179 | /** Removes and destroys all tracks making up this animation. */ |
---|
| 180 | void destroyAllNumericTracks(void); |
---|
| 181 | /** Removes and destroys all tracks making up this animation. */ |
---|
| 182 | void destroyAllVertexTracks(void); |
---|
| 183 | |
---|
| 184 | /** Applies an animation given a specific time point and weight. |
---|
| 185 | @remarks |
---|
| 186 | Where you have associated animation tracks with objects, you can eaily apply |
---|
| 187 | an animation to those objects by calling this method. |
---|
| 188 | @param timePos The time position in the animation to apply. |
---|
| 189 | @param weight The influence to give to this track, 1.0 for full influence, less to blend with |
---|
| 190 | other animations. |
---|
| 191 | @param scale The scale to apply to translations and scalings, useful for |
---|
| 192 | adapting an animation to a different size target. |
---|
| 193 | */ |
---|
| 194 | void apply(Real timePos, Real weight = 1.0, Real scale = 1.0f); |
---|
| 195 | |
---|
| 196 | /** Applies all node tracks given a specific time point and weight to a given skeleton. |
---|
| 197 | @remarks |
---|
| 198 | Where you have associated animation tracks with Node objects, you can eaily apply |
---|
| 199 | an animation to those nodes by calling this method. |
---|
| 200 | @param timePos The time position in the animation to apply. |
---|
| 201 | @param weight The influence to give to this track, 1.0 for full influence, less to blend with |
---|
| 202 | other animations. |
---|
| 203 | @param scale The scale to apply to translations and scalings, useful for |
---|
| 204 | adapting an animation to a different size target. |
---|
| 205 | */ |
---|
| 206 | void apply(Skeleton* skeleton, Real timePos, Real weight = 1.0, Real scale = 1.0f); |
---|
| 207 | |
---|
| 208 | /** Applies all vertex tracks given a specific time point and weight to a given entity. |
---|
| 209 | @remarks |
---|
| 210 | @param entity The Entity to which this animation should be applied |
---|
| 211 | @param timePos The time position in the animation to apply. |
---|
| 212 | @param weight The weight at which the animation should be applied |
---|
| 213 | (only affects pose animation) |
---|
| 214 | @param software Whether to populate the software morph vertex data |
---|
| 215 | @param hardware Whether to populate the hardware morph vertex data |
---|
| 216 | */ |
---|
| 217 | void apply(Entity* entity, Real timePos, Real weight, bool software, |
---|
| 218 | bool hardware); |
---|
| 219 | |
---|
| 220 | /** Tells the animation how to interpolate between keyframes. |
---|
| 221 | @remarks |
---|
| 222 | By default, animations normally interpolate linearly between keyframes. This is |
---|
| 223 | fast, but when animations include quick changes in direction it can look a little |
---|
| 224 | unnatural because directions change instantly at keyframes. An alternative is to |
---|
| 225 | tell the animation to interpolate along a spline, which is more expensive in terms |
---|
| 226 | of calculation time, but looks smoother because major changes in direction are |
---|
| 227 | distributed around the keyframes rather than just at the keyframe. |
---|
| 228 | @par |
---|
| 229 | You can also change the default animation behaviour by calling |
---|
| 230 | Animation::setDefaultInterpolationMode. |
---|
| 231 | */ |
---|
| 232 | void setInterpolationMode(InterpolationMode im); |
---|
| 233 | |
---|
| 234 | /** Gets the current interpolation mode of this animation. |
---|
| 235 | @remarks |
---|
| 236 | See setInterpolationMode for more info. |
---|
| 237 | */ |
---|
| 238 | InterpolationMode getInterpolationMode(void) const; |
---|
| 239 | /** Tells the animation how to interpolate rotations. |
---|
| 240 | @remarks |
---|
| 241 | By default, animations interpolate linearly between rotations. This |
---|
| 242 | is fast but not necessarily completely accurate. If you want more |
---|
| 243 | accurate interpolation, use spherical interpolation, but be aware |
---|
| 244 | that it will incur a higher cost. |
---|
| 245 | @par |
---|
| 246 | You can also change the default rotation behaviour by calling |
---|
| 247 | Animation::setDefaultRotationInterpolationMode. |
---|
| 248 | */ |
---|
| 249 | void setRotationInterpolationMode(RotationInterpolationMode im); |
---|
| 250 | |
---|
| 251 | /** Gets the current rotation interpolation mode of this animation. |
---|
| 252 | @remarks |
---|
| 253 | See setRotationInterpolationMode for more info. |
---|
| 254 | */ |
---|
| 255 | RotationInterpolationMode getRotationInterpolationMode(void) const; |
---|
| 256 | |
---|
| 257 | // Methods for setting the defaults |
---|
| 258 | /** Sets the default animation interpolation mode. |
---|
| 259 | @remarks |
---|
| 260 | Every animation created after this option is set will have the new interpolation |
---|
| 261 | mode specified. You can also change the mode per animation by calling the |
---|
| 262 | setInterpolationMode method on the instance in question. |
---|
| 263 | */ |
---|
| 264 | static void setDefaultInterpolationMode(InterpolationMode im); |
---|
| 265 | |
---|
| 266 | /** Gets the default interpolation mode for all animations. */ |
---|
| 267 | static InterpolationMode getDefaultInterpolationMode(void); |
---|
| 268 | |
---|
| 269 | /** Sets the default rotation interpolation mode. |
---|
| 270 | @remarks |
---|
| 271 | Every animation created after this option is set will have the new interpolation |
---|
| 272 | mode specified. You can also change the mode per animation by calling the |
---|
| 273 | setInterpolationMode method on the instance in question. |
---|
| 274 | */ |
---|
| 275 | static void setDefaultRotationInterpolationMode(RotationInterpolationMode im); |
---|
| 276 | |
---|
| 277 | /** Gets the default rotation interpolation mode for all animations. */ |
---|
| 278 | static RotationInterpolationMode getDefaultRotationInterpolationMode(void); |
---|
| 279 | |
---|
| 280 | typedef std::map<unsigned short, NodeAnimationTrack*> NodeTrackList; |
---|
| 281 | typedef ConstMapIterator<NodeTrackList> NodeTrackIterator; |
---|
| 282 | |
---|
| 283 | typedef std::map<unsigned short, NumericAnimationTrack*> NumericTrackList; |
---|
| 284 | typedef ConstMapIterator<NumericTrackList> NumericTrackIterator; |
---|
| 285 | |
---|
| 286 | typedef std::map<unsigned short, VertexAnimationTrack*> VertexTrackList; |
---|
| 287 | typedef ConstMapIterator<VertexTrackList> VertexTrackIterator; |
---|
| 288 | |
---|
| 289 | /// Fast access to NON-UPDATEABLE node track list |
---|
| 290 | const NodeTrackList& _getNodeTrackList(void) const; |
---|
| 291 | |
---|
| 292 | /// Get non-updateable iterator over node tracks |
---|
| 293 | NodeTrackIterator getNodeTrackIterator(void) const |
---|
| 294 | { return NodeTrackIterator(mNodeTrackList.begin(), mNodeTrackList.end()); } |
---|
| 295 | |
---|
| 296 | /// Fast access to NON-UPDATEABLE numeric track list |
---|
| 297 | const NumericTrackList& _getNumericTrackList(void) const; |
---|
| 298 | |
---|
| 299 | /// Get non-updateable iterator over node tracks |
---|
| 300 | NumericTrackIterator getNumericTrackIterator(void) const |
---|
| 301 | { return NumericTrackIterator(mNumericTrackList.begin(), mNumericTrackList.end()); } |
---|
| 302 | |
---|
| 303 | /// Fast access to NON-UPDATEABLE Vertex track list |
---|
| 304 | const VertexTrackList& _getVertexTrackList(void) const; |
---|
| 305 | |
---|
| 306 | /// Get non-updateable iterator over node tracks |
---|
| 307 | VertexTrackIterator getVertexTrackIterator(void) const |
---|
| 308 | { return VertexTrackIterator(mVertexTrackList.begin(), mVertexTrackList.end()); } |
---|
| 309 | |
---|
| 310 | /** Optimise an animation by removing unnecessary tracks and keyframes. |
---|
| 311 | @remarks |
---|
| 312 | When you export an animation, it is possible that certain tracks |
---|
| 313 | have been keyframed but actually don't include anything useful - the |
---|
| 314 | keyframes include no transformation. These tracks can be completely |
---|
| 315 | eliminated from the animation and thus speed up the animation. |
---|
| 316 | In addition, if several keyframes in a row have the same value, |
---|
| 317 | then they are just adding overhead and can be removed. |
---|
| 318 | @note |
---|
| 319 | Since track-less and identity track has difference behavior for |
---|
| 320 | accumulate animation blending if corresponding track presenting at |
---|
| 321 | other animation that is non-identity, and in normally this method |
---|
| 322 | didn't known about the situation of other animation, it can't deciding |
---|
| 323 | whether or not discards identity tracks. So there have a parameter |
---|
| 324 | allow you choose what you want, in case you aren't sure how to do that, |
---|
| 325 | you should use Skeleton::optimiseAllAnimations instead. |
---|
| 326 | @param |
---|
| 327 | discardIdentityNodeTracks If true, discard identity node tracks. |
---|
| 328 | */ |
---|
| 329 | void optimise(bool discardIdentityNodeTracks = true); |
---|
| 330 | |
---|
| 331 | /// A list of track handles |
---|
| 332 | typedef std::set<ushort> TrackHandleList; |
---|
| 333 | |
---|
| 334 | /** Internal method for collecting identity node tracks. |
---|
| 335 | @remarks |
---|
| 336 | This method remove non-identity node tracks form the track handle list. |
---|
| 337 | @param |
---|
| 338 | tracks A list of track handle of non-identity node tracks, where this |
---|
| 339 | method will remove non-identity node track handles. |
---|
| 340 | */ |
---|
| 341 | void _collectIdentityNodeTracks(TrackHandleList& tracks) const; |
---|
| 342 | |
---|
| 343 | /** Internal method for destroy given node tracks. |
---|
| 344 | */ |
---|
| 345 | void _destroyNodeTracks(const TrackHandleList& tracks); |
---|
| 346 | |
---|
| 347 | /** Clone this animation. |
---|
| 348 | @note |
---|
| 349 | The pointer returned from this method is the only one recorded, |
---|
| 350 | thus it is up to the caller to arrange for the deletion of this |
---|
| 351 | object. |
---|
| 352 | */ |
---|
| 353 | Animation* clone(const String& newName) const; |
---|
| 354 | |
---|
| 355 | /** Internal method used to tell the animation that keyframe list has been |
---|
| 356 | changed, which may cause it to rebuild some internal data */ |
---|
| 357 | void _keyFrameListChanged(void) { mKeyFrameTimesDirty = true; } |
---|
| 358 | |
---|
| 359 | /** Internal method used to convert time position to time index object. |
---|
| 360 | @note |
---|
| 361 | The time index returns by this function are associated with state of |
---|
| 362 | the animation object, if the animation object altered (e.g. create/remove |
---|
| 363 | keyframe or track), all related time index will invalidated. |
---|
| 364 | @param timePos The time position. |
---|
| 365 | @returns The time index object which contains wrapped time position (in |
---|
| 366 | relation to the whole animation sequence) and lower bound index of |
---|
| 367 | global keyframe time list. |
---|
| 368 | */ |
---|
| 369 | TimeIndex _getTimeIndex(Real timePos) const; |
---|
| 370 | |
---|
| 371 | protected: |
---|
| 372 | /// Node tracks, indexed by handle |
---|
| 373 | NodeTrackList mNodeTrackList; |
---|
| 374 | /// Numeric tracks, indexed by handle |
---|
| 375 | NumericTrackList mNumericTrackList; |
---|
| 376 | /// Vertex tracks, indexed by handle |
---|
| 377 | VertexTrackList mVertexTrackList; |
---|
| 378 | String mName; |
---|
| 379 | |
---|
| 380 | Real mLength; |
---|
| 381 | |
---|
| 382 | InterpolationMode mInterpolationMode; |
---|
| 383 | RotationInterpolationMode mRotationInterpolationMode; |
---|
| 384 | |
---|
| 385 | static InterpolationMode msDefaultInterpolationMode; |
---|
| 386 | static RotationInterpolationMode msDefaultRotationInterpolationMode; |
---|
| 387 | |
---|
| 388 | /// Global keyframe time list used to search global keyframe index. |
---|
| 389 | typedef std::vector<Real> KeyFrameTimeList; |
---|
| 390 | mutable KeyFrameTimeList mKeyFrameTimes; |
---|
| 391 | /// Dirty flag indicate that keyframe time list need to rebuild |
---|
| 392 | mutable bool mKeyFrameTimesDirty; |
---|
| 393 | |
---|
| 394 | void optimiseNodeTracks(bool discardIdentityTracks); |
---|
| 395 | void optimiseVertexTracks(void); |
---|
| 396 | |
---|
| 397 | /// Internal method to build global keyframe time list |
---|
| 398 | void buildKeyFrameTimeList(void) const; |
---|
| 399 | }; |
---|
| 400 | |
---|
| 401 | |
---|
| 402 | } |
---|
| 403 | |
---|
| 404 | |
---|
| 405 | #endif |
---|
| 406 | |
---|