source: GTP/trunk/App/Demos/Geom/OgreStuff/include/OgreNode.h @ 1092

Revision 1092, 28.8 KB checked in by gumbau, 18 years ago (diff)

LodStrips? and LODTrees demos

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#ifndef _Node_H__
26#define _Node_H__
27
28#include "OgrePrerequisites.h"
29
30#include "OgreMatrix3.h"
31#include "OgreMatrix4.h"
32#include "OgreQuaternion.h"
33#include "OgreString.h"
34#include "OgreRenderable.h"
35#include "OgreIteratorWrappers.h"
36
37namespace Ogre {
38
39
40    /** Class representing a general-purpose node an articulated scene graph.
41        @remarks
42            A node in the scene graph is a node in a structured tree. A node contains
43            information about the transformation which will apply to
44            it and all of it's children. Child nodes can have transforms of their own, which
45            are combined with their parent's transformations.
46        @par
47            This is an abstract class - concrete classes are based on this for specific purposes,
48            e.g. SceneNode, Bone
49    */
50    class _OgreExport Node : public Renderable
51    {
52    public:
53        /** Enumeration denoting the spaces which a transform can be relative to.
54        */
55        enum TransformSpace
56        {
57            /// Transform is relative to the local space
58            TS_LOCAL,
59            /// Transform is relative to the space of the parent node
60            TS_PARENT,
61            /// Transform is relative to world space
62            TS_WORLD
63        };
64        typedef HashMap<String, Node*> ChildNodeMap;
65        typedef MapIterator<ChildNodeMap> ChildNodeIterator;
66                typedef ConstMapIterator<ChildNodeMap> ConstChildNodeIterator;
67
68    protected:
69        /// Pointer to parent node
70        Node* mParent;
71        /// Collection of pointers to direct children; hashmap for efficiency
72        ChildNodeMap mChildren;
73
74                typedef std::set<Node*> ChildUpdateSet;
75        /// List of children which need updating, used if self is not out of date but children are
76        mutable ChildUpdateSet mChildrenToUpdate;
77        /// Flag to indicate own transform from parent is out of date
78        mutable bool mNeedParentUpdate;
79                /// Flag indicating that all children need to be updated
80                mutable bool mNeedChildUpdate;
81                /// Flag indicating that parent has been notified about update request
82            mutable bool mParentNotified ;
83
84        /// Friendly name of this node, can be automatically generated if you don't care
85        String mName;
86
87        /// Incremented count for next name extension
88        static unsigned long msNextGeneratedNameExt;
89
90        /// Stores the orientation of the node relative to it's parent.
91        Quaternion mOrientation;
92
93        /// Stores the position/translation of the node relative to its parent.
94        Vector3 mPosition;
95
96        /// Stores the scaling factor applied to this node
97        Vector3 mScale;
98
99        /// Stores whether this node inherits scale from it's parent
100        bool mInheritScale;
101
102                /// Material pointer should this node be rendered
103                mutable MaterialPtr mpMaterial;
104
105        /// Only available internally - notification of parent.
106        virtual void setParent(Node* parent);
107
108        /** Cached combined orientation.
109            @par
110                This member is the orientation derived by combining the
111                local transformations and those of it's parents.
112                This is updated when _updateFromParent is called by the
113                SceneManager or the nodes parent.
114        */
115        mutable Quaternion mDerivedOrientation;
116
117        /** Cached combined position.
118            @par
119                This member is the position derived by combining the
120                local transformations and those of it's parents.
121                This is updated when _updateFromParent is called by the
122                SceneManager or the nodes parent.
123        */
124        mutable Vector3 mDerivedPosition;
125
126        /** Cached combined scale.
127            @par
128                This member is the position derived by combining the
129                local transformations and those of it's parents.
130                This is updated when _updateFromParent is called by the
131                SceneManager or the nodes parent.
132        */
133        mutable Vector3 mDerivedScale;
134
135        /** Triggers the node to update it's combined transforms.
136            @par
137                This method is called internally by Ogre to ask the node
138                to update it's complete transformation based on it's parents
139                derived transform.
140        */
141        virtual void _updateFromParent(void) const;
142
143        /** Internal method for creating a new child node - must be overridden per subclass. */
144        virtual Node* createChildImpl(void) = 0;
145
146        /** Internal method for creating a new child node - must be overridden per subclass. */
147        virtual Node* createChildImpl(const String& name) = 0;
148
149        /** Internal method for building a Matrix4 from orientation / scale / position.
150        @remarks
151            Transform is performed in the order rotate, scale, translation, i.e. translation is independent
152            of orientation axes, scale does not affect size of translation, rotation and scaling are always
153            centered on the origin.
154        */
155        void makeTransform(
156            const Vector3& position,
157            const Vector3& scale,
158            const Quaternion& orientation,
159            Matrix4& destMatrix ) const;
160
161        /** Internal method for building an inverse Matrix4 from orientation / scale / position.
162        @remarks
163            As makeTransform except it build the inverse given the same data as makeTransform, so
164            performing -translation, 1/scale, -rotate in that order.
165        */
166        void makeInverseTransform(
167            const Vector3& position,
168            const Vector3& scale,
169            const Quaternion& orientation,
170            Matrix4& destMatrix );
171
172        /// The position to use as a base for keyframe animation
173        Vector3 mInitialPosition;
174        /// The orientation to use as a base for keyframe animation
175        Quaternion mInitialOrientation;
176        /// The scale to use as a base for keyframe animation
177        Vector3 mInitialScale;
178
179        // Weight of applied animations so far, used for blending
180        Real mAccumAnimWeight;
181        // The total weighted translation from the initial state so far
182        Vector3 mTransFromInitial;
183        // The total weighted rotation from the initial state so far
184        Quaternion mRotFromInitial;
185        // The total weighted scale from the initial state so far
186        Vector3 mScaleFromInitial;
187
188        /// Cached derived transform as a 4x4 matrix
189        mutable Matrix4 mCachedTransform;
190        mutable bool mCachedTransformOutOfDate;
191
192
193    public:
194        /** Constructor, should only be called by parent, not directly.
195        @remarks
196            Generates a name.
197        */
198        Node();
199        /** Constructor, should only be called by parent, not directly.
200        @remarks
201            Assigned a name.
202        */
203        Node(const String& name);
204
205        virtual ~Node(); 
206
207        /** Returns the name of the node. */
208        const String& getName(void) const;
209
210        /** Gets this node's parent (NULL if this is the root).
211        */
212        virtual Node* getParent(void) const;
213
214        /** Returns a quaternion representing the nodes orientation.
215        */
216        virtual const Quaternion & getOrientation() const;
217
218        /** Sets the orientation of this node via a quaternion.
219        */
220        virtual void setOrientation( const Quaternion& q );
221
222        /** Sets the orientation of this node via quaternion parameters.
223        */
224        virtual void setOrientation( Real w, Real x, Real y, Real z);
225
226        /** Resets the nodes orientation (local axes as world axes, no rotation).
227        */
228        virtual void resetOrientation(void);
229
230        /** Sets the position of the node relative to it's parent.
231        */
232        virtual void setPosition(const Vector3& pos);
233
234        /** Sets the position of the node relative to it's parent.
235        */
236        virtual void setPosition(Real x, Real y, Real z);
237
238        /** Gets the position of the node relative to it's parent.
239        */
240        virtual const Vector3 & getPosition(void) const;
241
242        /** Sets the scaling factor applied to this node.
243        @remarks
244            Scaling factors, unlike other transforms, are not always inherited by child nodes.
245            Whether or not scalings affect both the size and position of the child nodes depends on
246            the setInheritScale option of the child. In some cases you want a scaling factor of a parent node
247            to apply to a child node (e.g. where the child node is a part of the same object, so you
248            want it to be the same relative size and position based on the parent's size), but
249            not in other cases (e.g. where the child node is just for positioning another object,
250            you want it to maintain it's own size and relative position). The default is to inherit
251            as with other transforms.
252        @par
253            Note that like rotations, scalings are oriented around the node's origin.
254        */
255        virtual void setScale(const Vector3& scale);
256
257        /** Sets the scaling factor applied to this node.
258        @remarks
259            Scaling factors, unlike other transforms, are not always inherited by child nodes.
260            Whether or not scalings affect both the size and position of the child nodes depends on
261            the setInheritScale option of the child. In some cases you want a scaling factor of a parent node
262            to apply to a child node (e.g. where the child node is a part of the same object, so you
263            want it to be the same relative size and position based on the parent's size), but
264            not in other cases (e.g. where the child node is just for positioning another object,
265            you want it to maintain it's own size and relative position). The default is to inherit
266            as with other transforms.
267        @par
268            Note that like rotations, scalings are oriented around the node's origin.
269        */
270        virtual void setScale(Real x, Real y, Real z);
271
272        /** Gets the scaling factor of this node.
273        */
274        virtual const Vector3 & getScale(void) const;
275
276        /** Tells the node whether it should inherit scaling factors from it's parent node.
277        @remarks
278            Scaling factors, unlike other transforms, are not always inherited by child nodes.
279            Whether or not scalings affect both the size and position of the child nodes depends on
280            the setInheritScale option of the child. In some cases you want a scaling factor of a parent node
281            to apply to a child node (e.g. where the child node is a part of the same object, so you
282            want it to be the same relative size and position based on the parent's size), but
283            not in other cases (e.g. where the child node is just for positioning another object,
284            you want it to maintain it's own size and relative position). The default is to inherit
285            as with other transforms.
286        @param inherit If true, this node's scale and position will be affected by its parent's scale. If false,
287            it will not be affected.
288        */
289        virtual void setInheritScale(bool inherit);
290
291        /** Returns true if this node is affected by scaling factors applied to the parent node.
292        @remarks
293            See setInheritScale for more info.
294        */
295        virtual bool getInheritScale(void) const;
296
297        /** Scales the node, combining it's current scale with the passed in scaling factor.
298        @remarks
299            This method applies an extra scaling factor to the node's existing scale, (unlike setScale
300            which overwrites it) combining it's current scale with the new one. E.g. calling this
301            method twice with Vector3(2,2,2) would have the same effect as setScale(Vector3(4,4,4)) if
302            the existing scale was 1.
303        @par
304            Note that like rotations, scalings are oriented around the node's origin.
305        */
306        virtual void scale(const Vector3& scale);
307
308        /** Scales the node, combining it's current scale with the passed in scaling factor.
309        @remarks
310            This method applies an extra scaling factor to the node's existing scale, (unlike setScale
311            which overwrites it) combining it's current scale with the new one. E.g. calling this
312            method twice with Vector3(2,2,2) would have the same effect as setScale(Vector3(4,4,4)) if
313            the existing scale was 1.
314        @par
315            Note that like rotations, scalings are oriented around the node's origin.
316        */
317        virtual void scale(Real x, Real y, Real z);
318
319        /** Moves the node along the cartesian axes.
320            @par
321                This method moves the node by the supplied vector along the
322                world cartesian axes, i.e. along world x,y,z
323            @param
324                d Vector with x,y,z values representing the translation.
325            @param
326                relativeTo The space which this transform is relative to.
327        */
328        virtual void translate(const Vector3& d, TransformSpace relativeTo = TS_PARENT);
329        /** Moves the node along the cartesian axes.
330            @par
331                This method moves the node by the supplied vector along the
332                world cartesian axes, i.e. along world x,y,z
333            @param
334                x
335            @param
336                y
337            @param
338                z Real x, y and z values representing the translation.
339            @param
340            relativeTo The space which this transform is relative to.
341        */
342        virtual void translate(Real x, Real y, Real z, TransformSpace relativeTo = TS_PARENT);
343        /** Moves the node along arbitrary axes.
344            @remarks
345                This method translates the node by a vector which is relative to
346                a custom set of axes.
347            @param
348                axes A 3x3 Matrix containg 3 column vectors each representing the
349                axes X, Y and Z respectively. In this format the standard cartesian
350                axes would be expressed as:
351                <pre>
352                1 0 0
353                0 1 0
354                0 0 1
355                </pre>
356                i.e. the identity matrix.
357            @param
358                move Vector relative to the axes above.
359            @param
360            relativeTo The space which this transform is relative to.
361        */
362        virtual void translate(const Matrix3& axes, const Vector3& move, TransformSpace relativeTo = TS_PARENT);
363        /** Moves the node along arbitrary axes.
364            @remarks
365            This method translates the node by a vector which is relative to
366            a custom set of axes.
367            @param
368                axes A 3x3 Matrix containg 3 column vectors each representing the
369                axes X, Y and Z respectively. In this format the standard cartesian
370                axes would be expressed as
371                <pre>
372                1 0 0
373                0 1 0
374                0 0 1
375                </pre>
376                i.e. the identity matrix.
377            @param
378                x,y,z Translation components relative to the axes above.
379            @param
380                relativeTo The space which this transform is relative to.
381        */
382        virtual void translate(const Matrix3& axes, Real x, Real y, Real z, TransformSpace relativeTo = TS_PARENT);
383
384        /** Rotate the node around the Z-axis.
385        */
386        virtual void roll(const Radian& angle, TransformSpace relativeTo = TS_LOCAL);
387#ifndef OGRE_FORCE_ANGLE_TYPES
388        inline void roll(Real degrees, TransformSpace relativeTo = TS_LOCAL) {
389                        roll ( Angle(degrees), relativeTo );
390                }
391#endif//OGRE_FORCE_ANGLE_TYPES
392
393        /** Rotate the node around the X-axis.
394        */
395        virtual void pitch(const Radian& angle, TransformSpace relativeTo = TS_LOCAL);
396#ifndef OGRE_FORCE_ANGLE_TYPES
397        inline void pitch(Real degrees, TransformSpace relativeTo = TS_LOCAL) {
398                        pitch ( Angle(degrees), relativeTo );
399                }
400#endif//OGRE_FORCE_ANGLE_TYPES
401
402        /** Rotate the node around the Y-axis.
403        */
404        virtual void yaw(const Radian& angle, TransformSpace relativeTo = TS_LOCAL);
405#ifndef OGRE_FORCE_ANGLE_TYPES
406        inline void yaw(Real degrees, TransformSpace relativeTo = TS_LOCAL) {
407                        yaw ( Angle(degrees), relativeTo );
408                }
409#endif//OGRE_FORCE_ANGLE_TYPES
410
411        /** Rotate the node around an arbitrary axis.
412        */
413        virtual void rotate(const Vector3& axis, const Radian& angle, TransformSpace relativeTo = TS_LOCAL);
414#ifndef OGRE_FORCE_ANGLE_TYPES
415        inline void rotate(const Vector3& axis, Real degrees, TransformSpace relativeTo = TS_LOCAL) {
416                        rotate ( axis, Angle(degrees), relativeTo );
417                }
418#endif//OGRE_FORCE_ANGLE_TYPES
419
420        /** Rotate the node around an aritrary axis using a Quarternion.
421        */
422        virtual void rotate(const Quaternion& q, TransformSpace relativeTo = TS_LOCAL);
423
424        /** Gets a matrix whose columns are the local axes based on
425            the nodes orientation relative to it's parent. */
426        virtual Matrix3 getLocalAxes(void) const;
427
428        /** Creates an unnamed new Node as a child of this node.
429        @param
430            translate Initial translation offset of child relative to parent
431        @param
432            rotate Initial rotation relative to parent
433        */
434        virtual Node* createChild(
435            const Vector3& translate = Vector3::ZERO,
436            const Quaternion& rotate = Quaternion::IDENTITY );
437
438        /** Creates a new named Node as a child of this node.
439        @remarks
440            This creates a child node with a given name, which allows you to look the node up from
441            the parent which holds this collection of nodes.
442            @param
443                translate Initial translation offset of child relative to parent
444            @param
445                rotate Initial rotation relative to parent
446        */
447        virtual Node* createChild(const String& name, const Vector3& translate = Vector3::ZERO, const Quaternion& rotate = Quaternion::IDENTITY);
448
449        /** Adds a (precreated) child scene node to this node. If it is attached to another node,
450            it must be detached first.
451        @param child The Node which is to become a child node of this one
452        */
453        virtual void addChild(Node* child);
454
455        /** Reports the number of child nodes under this one.
456        */
457        virtual unsigned short numChildren(void) const;
458
459        /** Gets a pointer to a child node.
460        @remarks
461            There is an alternate getChild method which returns a named child.
462        */
463        virtual Node* getChild(unsigned short index) const;   
464
465        /** Gets a pointer to a named child node.
466        */
467        virtual Node* getChild(const String& name) const;
468
469        /** Retrieves an iterator for efficiently looping through all children of this node.
470        @remarks
471            Using this is faster than repeatedly calling getChild if you want to go through
472            all (or most of) the children of this node.
473            Note that the returned iterator is only valid whilst no children are added or
474            removed from this node. Thus you should not store this returned iterator for
475            later use, nor should you add / remove children whilst iterating through it;
476            store up changes for later. Note that calling methods on returned items in
477            the iterator IS allowed and does not invalidate the iterator.
478        */
479        virtual ChildNodeIterator getChildIterator(void);
480
481        /** Retrieves an iterator for efficiently looping through all children of this node.
482        @remarks
483            Using this is faster than repeatedly calling getChild if you want to go through
484            all (or most of) the children of this node.
485            Note that the returned iterator is only valid whilst no children are added or
486            removed from this node. Thus you should not store this returned iterator for
487            later use, nor should you add / remove children whilst iterating through it;
488            store up changes for later. Note that calling methods on returned items in
489            the iterator IS allowed and does not invalidate the iterator.
490        */
491                virtual ConstChildNodeIterator getChildIterator(void) const;
492
493        /** Drops the specified child from this node.
494        @remarks
495            Does not delete the node, just detaches it from
496            this parent, potentially to be reattached elsewhere.
497            There is also an alternate version which drops a named
498            child from this node.
499        */
500        virtual Node* removeChild(unsigned short index);
501        /** Drops the specified child from this node.
502        @remarks
503        Does not delete the node, just detaches it from
504        this parent, potentially to be reattached elsewhere.
505        There is also an alternate version which drops a named
506        child from this node.
507        */
508        virtual Node* removeChild(Node* child);
509
510        /** Drops the named child from this node.
511        @remarks
512            Does not delete the node, just detaches it from
513            this parent, potentially to be reattached elsewhere.
514        */
515        virtual Node* removeChild(const String& name);
516        /** Removes all child Nodes attached to this node. Does not delete the nodes, just detaches them from
517            this parent, potentially to be reattached elsewhere.
518        */
519        virtual void removeAllChildren(void);
520
521        /** Gets the orientation of the node as derived from all parents.
522        */
523        virtual const Quaternion & _getDerivedOrientation(void) const;
524
525        /** Gets the position of the node as derived from all parents.
526        */
527        virtual const Vector3 & _getDerivedPosition(void) const;
528
529        /** Gets the scaling factor of the node as derived from all parents.
530        */
531        virtual const Vector3 & _getDerivedScale(void) const;
532
533        /** Gets the full transformation matrix for this node.
534            @remarks
535                This method returns the full transformation matrix
536                for this node, including the effect of any parent node
537                transformations, provided they have been updated using the Node::_update method.
538                This should only be called by a SceneManager which knows the
539                derived transforms have been updated before calling this method.
540                Applications using Ogre should just use the relative transforms.
541        */
542        virtual Matrix4 _getFullTransform(void) const;
543
544        /** Internal method to update the Node.
545            @note
546                Updates this node and any relevant children to incorporate transforms etc.
547                Don't call this yourself unless you are writing a SceneManager implementation.
548            @param
549                updateChildren If true, the update cascades down to all children. Specify false if you wish to
550                update children separately, e.g. because of a more selective SceneManager implementation.
551            @param
552                parentHasChanged This flag indicates that the parent xform has changed,
553                    so the child should retrieve the parent's xform and combine it with its own
554                    even if it hasn't changed itself.
555        */
556        virtual void _update(bool updateChildren, bool parentHasChanged);
557
558        /** Overridden from Renderable.
559        @remarks
560            This is only used if the SceneManager chooses to render the node. This option can be set
561            for SceneNodes at SceneManager::setDisplaySceneNodes, and for entities based on skeletal
562            models using Entity::setDisplayBones()
563        */
564        const MaterialPtr& getMaterial(void) const;
565        /** Overridden from Renderable.
566        @remarks
567            This is only used if the SceneManager chooses to render the node. This option can be set
568            for SceneNodes at SceneManager::setDisplaySceneNodes, and for entities based on skeletal
569            models using Entity::setDisplaySkeleton()
570        */
571        void getRenderOperation(RenderOperation& op);
572        /** Overridden from Renderable.
573        @remarks
574            This is only used if the SceneManager chooses to render the node. This option can be set
575            for SceneNodes at SceneManager::setDisplaySceneNodes, and for entities based on skeletal
576            models using Entity::setDisplaySkeleton()
577        */
578        void getWorldTransforms(Matrix4* xform) const;
579        /** @copydoc Renderable::getWorldOrientation */
580        const Quaternion& getWorldOrientation(void) const;
581        /** @copydoc Renderable::getWorldPosition */
582        const Vector3& getWorldPosition(void) const;
583
584        /** Sets the current transform of this node to be the 'initial state' ie that
585            position / orientation / scale to be used as a basis for delta values used
586            in keyframe animation.
587        @remarks
588            You never need to call this method unless you plan to animate this node. If you do
589            plan to animate it, call this method once you've loaded the node with it's base state,
590            ie the state on which all keyframes are based.
591        @par
592            If you never call this method, the initial state is the identity transform, ie do nothing.
593        */
594        virtual void setInitialState(void);
595
596        /** Resets the position / orientation / scale of this node to it's initial state, see setInitialState for more info. */
597        virtual void resetToInitialState(void);
598
599        /** Gets the initial position of this node, see setInitialState for more info.
600        @remarks
601            Also resets the cumulative animation weight used for blending.
602        */
603        virtual const Vector3& getInitialPosition(void) const;
604
605        /** Gets the initial orientation of this node, see setInitialState for more info. */
606        virtual const Quaternion& getInitialOrientation(void) const;
607
608        /** Gets the initial position of this node, see setInitialState for more info. */
609        virtual const Vector3& getInitialScale(void) const;
610
611        /** Internal weighted transform method.
612        @remarks
613            This method transforms a Node by a weighted amount from it's
614            initial state. If weighted transforms have already been applied,
615            the previous transforms and this one are blended together based
616            on their relative weight. This method should not be used in
617            combination with the unweighted rotate, translate etc methods.
618        */
619        virtual void _weightedTransform(Real weight, const Vector3& translate,
620            const Quaternion& rotate, const Vector3& scale);
621
622        /** Overridden, see Renderable */
623        Real getSquaredViewDepth(const Camera* cam) const;
624
625        /** To be called in the event of transform changes to this node that require it's recalculation.
626        @remarks
627            This not only tags the node state as being 'dirty', it also requests it's parent to
628            know about it's dirtiness so it will get an update next time.
629        */
630        virtual void needUpdate();
631        /** Called by children to notify their parent that they need an update. */
632        virtual void requestUpdate(Node* child);
633        /** Called by children to notify their parent that they no longer need an update. */
634        virtual void cancelUpdate(Node* child);
635
636        /** @copydoc Renderable::getLights */
637        const LightList& getLights(void) const;
638
639
640
641    };
642
643} //namespace
644
645#endif
Note: See TracBrowser for help on using the repository browser.