Planet
navi homePPSaboutscreenshotsdownloaddevelopmentforum

source: downloads/ogre_src_v1-9-0/OgreMain/include/OgreSkeleton.h @ 148

Last change on this file since 148 was 148, checked in by patricwi, 6 years ago

Added new dependencies for ogre1.9 and cegui0.8

File size: 22.3 KB
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-2013 Torus Knot Software Ltd
8
9Permission is hereby granted, free of charge, to any person obtaining a copy
10of this software and associated documentation files (the "Software"), to deal
11in the Software without restriction, including without limitation the rights
12to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
13copies of the Software, and to permit persons to whom the Software is
14furnished to do so, subject to the following conditions:
15
16The above copyright notice and this permission notice shall be included in
17all copies or substantial portions of the Software.
18
19THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
20IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
21FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
22AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
23LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
24OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
25THE SOFTWARE.
26-----------------------------------------------------------------------------
27*/
28
29#ifndef __Skeleton_H__
30#define __Skeleton_H__
31
32#include "OgrePrerequisites.h"
33#include "OgreResource.h"
34#include "OgreQuaternion.h"
35#include "OgreVector3.h"
36#include "OgreIteratorWrappers.h"
37#include "OgreStringVector.h"
38#include "OgreAnimation.h"
39#include "OgreHeaderPrefix.h"
40
41namespace Ogre {
42        /** \addtogroup Core
43        *  @{
44        */
45        /** \addtogroup Animation
46        *  @{
47        */
48
49    /**  */
50    enum SkeletonAnimationBlendMode {
51        /// Animations are applied by calculating a weighted average of all animations
52            ANIMBLEND_AVERAGE = 0,
53        /// Animations are applied by calculating a weighted cumulative total
54            ANIMBLEND_CUMULATIVE = 1
55    };
56
57#define OGRE_MAX_NUM_BONES 256
58
59       
60        struct LinkedSkeletonAnimationSource;
61
62    /** A collection of Bone objects used to animate a skinned mesh.
63    @remarks
64        Skeletal animation works by having a collection of 'bones' which are
65        actually just joints with a position and orientation, arranged in a tree structure.
66        For example, the wrist joint is a child of the elbow joint, which in turn is a
67        child of the shoulder joint. Rotating the shoulder automatically moves the elbow
68        and wrist as well due to this hierarchy.
69    @par
70        So how does this animate a mesh? Well every vertex in a mesh is assigned to one or more
71        bones which affects it's position when the bone is moved. If a vertex is assigned to
72        more than one bone, then weights must be assigned to determine how much each bone affects
73        the vertex (actually a weight of 1.0 is used for single bone assignments).
74        Weighted vertex assignments are especially useful around the joints themselves
75        to avoid 'pinching' of the mesh in this region.
76    @par
77        Therefore by moving the skeleton using preset animations, we can animate the mesh. The
78        advantage of using skeletal animation is that you store less animation data, especially
79        as vertex counts increase. In addition, you are able to blend multiple animations together
80        (e.g. walking and looking around, running and shooting) and provide smooth transitions
81        between animations without incurring as much of an overhead as would be involved if you
82        did this on the core vertex data.
83    @par
84        Skeleton definitions are loaded from datafiles, namely the .skeleton file format. They
85        are loaded on demand, especially when referenced by a Mesh.
86    */
87    class _OgreExport Skeleton : public Resource, public AnimationContainer
88    {
89                friend class SkeletonInstance;
90        protected:
91                /// Internal constructor for use by SkeletonInstance only
92                Skeleton();
93
94    public:
95        /** Constructor, don't call directly, use SkeletonManager.
96        @remarks
97            On creation, a Skeleton has a no bones, you should create them and link
98            them together appropriately.
99        */
100        Skeleton(ResourceManager* creator, const String& name, ResourceHandle handle,
101            const String& group, bool isManual = false, ManualResourceLoader* loader = 0);
102        virtual ~Skeleton();
103
104
105        /** Creates a brand new Bone owned by this Skeleton.
106        @remarks
107            This method creates an unattached new Bone for this skeleton.
108                        Unless this is to be a root bone (there may be more than one of
109                        these), you must attach it to another Bone in the skeleton using addChild for it to be any use.
110            For this reason you will likely be better off creating child bones using the
111            Bone::createChild method instead, once you have created the root bone.
112        @par
113            Note that this method automatically generates a handle for the bone, which you
114            can retrieve using Bone::getHandle. If you wish the new Bone to have a specific
115            handle, use the alternate form of this method which takes a handle as a parameter,
116            although you should note the restrictions.
117        */
118        virtual Bone* createBone(void);
119
120        /** Creates a brand new Bone owned by this Skeleton.
121        @remarks
122            This method creates an unattached new Bone for this skeleton and assigns it a
123            specific handle. Unless this is to be a root bone (there may be more than one of
124                        these), you must attach it to another Bone in the skeleton using addChild for it to be any use.
125            For this reason you will likely be better off creating child bones using the
126            Bone::createChild method instead, once you have created a root bone.
127        @param handle The handle to give to this new bone - must be unique within this skeleton.
128            You should also ensure that all bone handles are eventually contiguous (this is to simplify
129            their compilation into an indexed array of transformation matrices). For this reason
130            it is advised that you use the simpler createBone method which automatically assigns a
131            sequential handle starting from 0.
132        */
133        virtual Bone* createBone(unsigned short handle);
134
135        /** Creates a brand new Bone owned by this Skeleton.
136        @remarks
137            This method creates an unattached new Bone for this skeleton and assigns it a
138            specific name.Unless this is to be a root bone (there may be more than one of
139                        these), you must attach it to another Bone in the skeleton using addChild for it to be any use.
140            For this reason you will likely be better off creating child bones using the
141            Bone::createChild method instead, once you have created the root bone.
142        @param name The name to give to this new bone - must be unique within this skeleton.
143            Note that the way OGRE looks up bones is via a numeric handle, so if you name a
144            Bone this way it will be given an automatic sequential handle. The name is just
145            for your convenience, although it is recommended that you only use the handle to
146            retrieve the bone in performance-critical code.
147        */
148        virtual Bone* createBone(const String& name);
149
150        /** Creates a brand new Bone owned by this Skeleton.
151        @remarks
152            This method creates an unattached new Bone for this skeleton and assigns it a
153            specific name and handle. Unless this is to be a root bone (there may be more than one of
154                        these), you must attach it to another Bone in the skeleton using addChild for it to be any use.
155            For this reason you will likely be better off creating child bones using the
156            Bone::createChild method instead, once you have created the root bone.
157        @param name The name to give to this new bone - must be unique within this skeleton.
158        @param handle The handle to give to this new bone - must be unique within this skeleton.
159        */
160        virtual Bone* createBone(const String& name, unsigned short handle);
161
162        /** Returns the number of bones in this skeleton. */
163        virtual unsigned short getNumBones(void) const;
164
165        /** Gets the root bone of the skeleton: deprecated in favour of getRootBoneIterator.
166        @remarks
167            The system derives the root bone the first time you ask for it. The root bone is the
168            only bone in the skeleton which has no parent. The system locates it by taking the
169            first bone in the list and going up the bone tree until there are no more parents,
170            and saves this top bone as the root. If you are building the skeleton manually using
171            createBone then you must ensure there is only one bone which is not a child of
172            another bone, otherwise your skeleton will not work properly. If you use createBone
173            only once, and then use Bone::createChild from then on, then inherently the first
174            bone you create will by default be the root.
175        */
176        virtual Bone* getRootBone(void) const;
177
178        typedef vector<Bone*>::type BoneList;
179        typedef VectorIterator<BoneList> BoneIterator;
180        /// Get an iterator over the root bones in the skeleton, ie those with no parents
181        virtual BoneIterator getRootBoneIterator(void);
182        /// Get an iterator over all the bones in the skeleton
183        virtual BoneIterator getBoneIterator(void);
184
185        /** Gets a bone by it's handle. */
186        virtual Bone* getBone(unsigned short handle) const;
187
188        /** Gets a bone by it's name. */
189        virtual Bone* getBone(const String& name) const;
190
191                /** Returns whether this skeleton contains the named bone. */
192        virtual bool hasBone(const String& name) const;
193
194        /** Sets the current position / orientation to be the 'binding pose' i.e. the layout in which
195            bones were originally bound to a mesh.
196        */
197        virtual void setBindingPose(void);
198
199        /** Resets the position and orientation of all bones in this skeleton to their original binding position.
200        @remarks
201            A skeleton is bound to a mesh in a binding pose. Bone positions are then modified from this
202            position during animation. This method returns all the bones to their original position and
203            orientation.
204        @param resetManualBones If set to true, causes the state of manual bones to be reset
205            too, which is normally not done to allow the manual state to persist even
206            when keyframe animation is applied.
207        */
208        virtual void reset(bool resetManualBones = false);
209
210        /** Creates a new Animation object for animating this skeleton.
211        @param name The name of this animation
212        @param length The length of the animation in seconds
213        */
214        virtual Animation* createAnimation(const String& name, Real length);
215
216        /** Returns the named Animation object.
217                @remarks
218                        Will pick up animations in linked skeletons
219                        (@see addLinkedSkeletonAnimationSource).
220                @param name The name of the animation
221                @param linker Optional pointer to a pointer to the linked skeleton animation
222                        where this is coming from.
223                */
224        virtual Animation* getAnimation(const String& name, 
225                        const LinkedSkeletonAnimationSource** linker) const;
226
227                /** Returns the named Animation object.
228                 @remarks
229                         Will pick up animations in linked skeletons
230                         (@see addLinkedSkeletonAnimationSource).
231                 @param name The name of the animation
232                 */
233                virtual Animation* getAnimation(const String& name) const;
234
235                /// Internal accessor for animations (returns null if animation does not exist)
236                virtual Animation* _getAnimationImpl(const String& name, 
237                        const LinkedSkeletonAnimationSource** linker = 0) const;
238
239
240                /** Returns whether this skeleton contains the named animation. */
241                virtual bool hasAnimation(const String& name) const;
242
243        /** Removes an Animation from this skeleton. */
244        virtual void removeAnimation(const String& name);
245
246        /** Changes the state of the skeleton to reflect the application of the passed in collection of animations.
247        @remarks
248            Animating a skeleton involves both interpolating between keyframes of a specific animation,
249            and blending between the animations themselves. Calling this method sets the state of
250            the skeleton so that it reflects the combination of all the passed in animations, at the
251            time index specified for each, using the weights specified. Note that the weights between
252            animations do not have to sum to 1.0, because some animations may affect only subsets
253            of the skeleton. If the weights exceed 1.0 for the same area of the skeleton, the
254            movement will just be exaggerated.
255        */
256        virtual void setAnimationState(const AnimationStateSet& animSet);
257
258
259        /** Initialise an animation set suitable for use with this skeleton.
260        @remarks
261            Only recommended for use inside the engine, not by applications.
262        */
263        virtual void _initAnimationState(AnimationStateSet* animSet);
264
265                /** Refresh an animation set suitable for use with this skeleton.
266                @remarks
267                        Only recommended for use inside the engine, not by applications.
268                */
269                virtual void _refreshAnimationState(AnimationStateSet* animSet);
270
271                /** Populates the passed in array with the bone matrices based on the current position.
272        @remarks
273            Internal use only. The array pointed to by the passed in pointer must
274            be at least as large as the number of bones.
275            Assumes animation has already been updated.
276        */
277        virtual void _getBoneMatrices(Matrix4* pMatrices);
278
279        /** Gets the number of animations on this skeleton. */
280        virtual unsigned short getNumAnimations(void) const;
281
282        /** Gets a single animation by index.
283                @remarks
284                        Will NOT pick up animations in linked skeletons
285                        (@see addLinkedSkeletonAnimationSource).
286                */
287        virtual Animation* getAnimation(unsigned short index) const;
288
289
290                /** Gets the animation blending mode which this skeleton will use. */
291        virtual SkeletonAnimationBlendMode getBlendMode() const;
292        /** Sets the animation blending mode this skeleton will use. */
293                virtual void setBlendMode(SkeletonAnimationBlendMode state);
294
295        /// Updates all the derived transforms in the skeleton
296        virtual void _updateTransforms(void);
297
298                /** Optimise all of this skeleton's animations.
299                @see Animation::optimise
300        @param
301            preservingIdentityNodeTracks If true, don't destroy identity node tracks.
302                */
303                virtual void optimiseAllAnimations(bool preservingIdentityNodeTracks = false);
304
305                /** Allows you to use the animations from another Skeleton object to animate
306                        this skeleton.
307                @remarks
308                        If you have skeletons of identical structure (that means identically
309                        named bones with identical handles, and with the same hierarchy), but
310                        slightly different proportions or binding poses, you can re-use animations
311                        from one in the other. Because animations are actually stored as
312                        changes to bones from their bind positions, it's possible to use the
313                        same animation data for different skeletons, provided the skeletal
314                        structure matches and the 'deltas' stored in the keyframes apply
315                        equally well to the other skeletons bind position (so they must be
316                        roughly similar, but don't have to be identical). You can use the
317                        'scale' option to adjust the translation and scale keyframes where
318                        there are large differences in size between the skeletons.
319                @note
320                        This method takes a skeleton name, rather than a more specific
321                        animation name, for two reasons; firstly it allows some validation
322                        of compatibility of skeletal structure, and secondly skeletons are
323                        the unit of loading. Linking a skeleton to another in this way means
324                        that the linkee will be prevented from being destroyed until the
325                        linker is destroyed.
326
327                        You cannot set up cyclic relationships, e.g. SkeletonA uses SkeletonB's
328                        animations, and SkeletonB uses SkeletonA's animations. This is because
329                        it would set up a circular dependency which would prevent proper
330                        unloading - make one of the skeletons the 'master' in this case.
331                @param skelName Name of the skeleton to link animations from. This
332                        skeleton will be loaded immediately if this skeleton is already
333                        loaded, otherwise it will be loaded when this skeleton is.
334                @param scale A scale factor to apply to translation and scaling elements
335                        of the keyframes in the other skeleton when applying the animations
336                        to this one. Compensates for skeleton size differences.
337                */
338                virtual void addLinkedSkeletonAnimationSource(const String& skelName, 
339                        Real scale = 1.0f);
340                /// Remove all links to other skeletons for the purposes of sharing animation
341                virtual void removeAllLinkedSkeletonAnimationSources(void);
342               
343                typedef vector<LinkedSkeletonAnimationSource>::type
344                        LinkedSkeletonAnimSourceList;
345                typedef ConstVectorIterator<LinkedSkeletonAnimSourceList> 
346                        LinkedSkeletonAnimSourceIterator;
347                /// Get an iterator over the linked skeletons used as animation sources
348                virtual LinkedSkeletonAnimSourceIterator
349                        getLinkedSkeletonAnimationSourceIterator(void) const;
350
351                /// Internal method for marking the manual bones as dirty
352                virtual void _notifyManualBonesDirty(void);
353                /// Internal method for notifying that a bone is manual
354                virtual void _notifyManualBoneStateChange(Bone* bone);
355
356                /// Have manual bones been modified since the skeleton was last updated?
357                virtual bool getManualBonesDirty(void) const { return mManualBonesDirty; }
358                /// Are there any manually controlled bones?
359                virtual bool hasManualBones(void) const { return !mManualBones.empty(); }
360
361        /// Map to translate bone handle from one skeleton to another skeleton.
362        typedef vector<ushort>::type BoneHandleMap;
363
364        /** Merge animations from another Skeleton object into this skeleton.
365        @remarks
366            This function allow merge two structures compatible skeletons. The
367            'compatible' here means identically bones will have same hierarchy,
368            but skeletons are not necessary to have same number of bones (if
369            number bones of source skeleton's more than this skeleton, they will
370            copied as is, except that duplicate names are disallowed; and in the
371            case of bones missing in source skeleton, nothing happen for those
372            bones).
373        @par
374            There are also unnecessary to have same binding poses, this function
375            will adjust keyframes of the source skeleton to match this skeleton
376            automatically.
377        @par
378            It's useful for exporting skeleton animations separately. i.e. export
379            mesh and 'master' skeleton at the same time, and then other animations
380            will export separately (even if used completely difference binding
381            pose), finally, merge separately exported animations into 'master'
382            skeleton.
383        @param
384            source Pointer to source skeleton. It'll keep unmodified.
385        @param
386            boneHandleMap A map to translate identically bone's handle from source
387            skeleton to this skeleton. If mapped bone handle doesn't exists in this
388            skeleton, it'll created. You can populate bone handle map manually, or
389            use predefined functions build bone handle map for you. (@see
390            _buildMapBoneByHandle, _buildMapBoneByName)
391        @param
392            animations A list name of animations to merge, if empty, all animations
393            of source skeleton are used to merge. Note that the animation names
394            must not presented in this skeleton, and will NOT pick up animations
395            in linked skeletons (@see addLinkedSkeletonAnimationSource).
396        */
397        virtual void _mergeSkeletonAnimations(const Skeleton* source,
398            const BoneHandleMap& boneHandleMap,
399            const StringVector& animations = StringVector());
400
401        /** Build the bone handle map to use with Skeleton::_mergeSkeletonAnimations.
402        @remarks
403            Identically bones are determine by handle.
404        */
405        virtual void _buildMapBoneByHandle(const Skeleton* source,
406            BoneHandleMap& boneHandleMap) const;
407
408        /** Build the bone handle map to use with Skeleton::_mergeSkeletonAnimations.
409        @remarks
410            Identically bones are determine by name.
411        */
412        virtual void _buildMapBoneByName(const Skeleton* source,
413            BoneHandleMap& boneHandleMap) const;
414
415        protected:
416                SkeletonAnimationBlendMode mBlendState;
417        /// Storage of bones, indexed by bone handle
418        BoneList mBoneList;
419        /// Lookup by bone name
420        typedef map<String, Bone*>::type BoneListByName;
421        BoneListByName mBoneListByName;
422
423
424        /// Pointer to root bones (can now have multiple roots)
425        mutable BoneList mRootBones;
426        /// Bone automatic handles
427        unsigned short mNextAutoHandle;
428                typedef set<Bone*>::type BoneSet;
429                /// Manual bones
430                BoneSet mManualBones;
431                /// Manual bones dirty?
432                bool mManualBonesDirty;
433
434
435        /// Storage of animations, lookup by name
436        typedef map<String, Animation*>::type AnimationList;
437        AnimationList mAnimationsList;
438
439                /// List of references to other skeletons to use animations from
440                mutable LinkedSkeletonAnimSourceList mLinkedSkeletonAnimSourceList;
441
442        /** Internal method which parses the bones to derive the root bone.
443        @remarks
444            Must be const because called in getRootBone but mRootBone is mutable
445            since lazy-updated.
446        */
447        void deriveRootBone(void) const;
448
449        /// Debugging method
450        void _dumpContents(const String& filename);
451
452        /** @copydoc Resource::loadImpl
453        */
454        void loadImpl(void);
455
456        /** @copydoc Resource::unloadImpl
457        */
458        void unloadImpl(void);
459                /// @copydoc Resource::calculateSize
460                size_t calculateSize(void) const;
461
462    };
463
464    typedef SharedPtr<Skeleton> SkeletonPtr;
465
466        /// Link to another skeleton to share animations
467        struct LinkedSkeletonAnimationSource
468        {
469                String skeletonName;
470                SkeletonPtr pSkeleton;
471                Real scale;
472                LinkedSkeletonAnimationSource(const String& skelName, Real scl)
473                        : skeletonName(skelName), scale(scl) {}
474                        LinkedSkeletonAnimationSource(const String& skelName, Real scl, 
475                                SkeletonPtr skelPtr)
476                                : skeletonName(skelName), pSkeleton(skelPtr), scale(scl) {}
477        };
478        /** @} */
479        /** @} */
480
481}
482
483#include "OgreHeaderSuffix.h"
484
485#endif
486
Note: See TracBrowser for help on using the repository browser.