source: GTP/trunk/Lib/Geom/OgreStuff/include/OgreSceneNode.h @ 1809

Revision 1809, 20.4 KB checked in by gumbau, 18 years ago (diff)
RevLine 
[1809]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 _SceneNode_H__
26#define _SceneNode_H__
27
28#include "OgrePrerequisites.h"
29
30#include "OgreNode.h"
31#include "OgreIteratorWrappers.h"
32#include "OgreAxisAlignedBox.h"
33
34namespace Ogre {
35
36    /** Class representing a node in the scene graph.
37        @remarks
38            A SceneNode is a type of Node which is used to organise objects in a scene.
39            It has the same hierarchical transformation properties of the generic Node class,
40            but also adds the ability to attach world objects to the node, and stores hierarchical
41            bounding volumes of the nodes in the tree.
42            Child nodes are contained within the bounds of the parent, and so on down the
43            tree, allowing for fast culling.
44    */
45    class _OgreExport SceneNode : public Node
46    {
47    public:
48        typedef HashMap<String, MovableObject*> ObjectMap;
49        typedef MapIterator<ObjectMap> ObjectIterator;
50                typedef ConstMapIterator<ObjectMap> ConstObjectIterator;
51
52    protected:
53        ObjectMap mObjectsByName;
54        mutable LightList mLightList;
55        mutable bool mLightListDirty;
56
57                /// Pointer to a Wire Bounding Box for this Node
58                WireBoundingBox *mWireBoundingBox;
59                /// Flag that determines if the bounding box of the node should be displayed
60                bool mShowBoundingBox;
61
62        /// SceneManager which created this node
63        SceneManager* mCreator;
64
65        /// World-Axis aligned bounding box, updated only through _update
66        AxisAlignedBox mWorldAABB;
67
68        /** See Node. */
69        Node* createChildImpl(void);
70
71        /** See Node. */
72        Node* createChildImpl(const String& name);
73
74                /** See Node */
75                void setParent(Node* parent);
76
77                /** Internal method for setting whether the node is in the scene
78                        graph.
79                */
80                virtual void setInSceneGraph(bool inGraph);
81
82        /// Whether to yaw around a fixed axis.
83        bool mYawFixed;
84        /// Fixed axis to yaw around
85        Vector3 mYawFixedAxis;
86
87        /// Auto tracking target
88        SceneNode* mAutoTrackTarget;
89        /// Tracking offset for fine tuning
90        Vector3 mAutoTrackOffset;
91        /// Local 'normal' direction vector
92        Vector3 mAutoTrackLocalDirection;
93                /// Is this node a current part of the scene graph?
94                bool mIsInSceneGraph;
95    public:
96        /** Constructor, only to be called by the creator SceneManager.
97        @remarks
98            Creates a node with a generated name.
99        */
100        SceneNode(SceneManager* creator);
101        /** Constructor, only to be called by the creator SceneManager.
102        @remarks
103            Creates a node with a specified name.
104        */
105        SceneNode(SceneManager* creator, const String& name);
106        ~SceneNode();
107
108        /** Adds an instance of a scene object to this node.
109        @remarks
110            Scene objects can include Entity objects, Camera objects, Light objects,
111            ParticleSystem objects etc. Anything that subclasses from MovableObject.
112        */
113        virtual void attachObject(MovableObject* obj);
114
115        /** Reports the number of objects attached to this node.
116        */
117        virtual unsigned short numAttachedObjects(void) const;
118
119        /** Retrieves a pointer to an attached object.
120        @remarks Retrieves by index, see alternate version to retrieve by name. The index
121        of an object may change as other objects are added / removed.
122        */
123        virtual MovableObject* getAttachedObject(unsigned short index);
124
125        /** Retrieves a pointer to an attached object.
126        @remarks Retrieves by object name, see alternate version to retrieve by index.
127        */
128        virtual MovableObject* getAttachedObject(const String& name);
129
130        /** Detaches the indexed object from this scene node.
131        @remarks
132            Detaches by index, see the alternate version to detach by name. Object indexes
133            may change as other objects are added / removed.
134        */
135        virtual MovableObject* detachObject(unsigned short index);
136        /** Detaches an object by pointer. */
137        virtual void detachObject(MovableObject* obj);
138
139        /** Detaches the named object from this node and returns a pointer to it. */
140        virtual MovableObject* detachObject(const String& name);
141
142        /** Detaches all objects attached to this node.
143        */
144        virtual void detachAllObjects(void);
145
146                /** Determines whether this node is in the scene graph, ie
147                        whether it's ulitimate ancestor is the root scene node.
148                */
149                virtual bool isInSceneGraph(void) const { return mIsInSceneGraph; }
150
151                /** Notifies this SceneNode that it is the root scene node.
152                @remarks
153                        Only SceneManager should call this!
154                */
155                virtual void _notifyRootNode(void) { mIsInSceneGraph = true; }
156                       
157
158        /** Internal method to update the Node.
159            @note
160                Updates this scene node and any relevant children to incorporate transforms etc.
161                Don't call this yourself unless you are writing a SceneManager implementation.
162            @param
163                updateChildren If true, the update cascades down to all children. Specify false if you wish to
164                update children separately, e.g. because of a more selective SceneManager implementation.
165            @param
166                parentHasChanged This flag indicates that the parent xform has changed,
167                    so the child should retrieve the parent's xform and combine it with its own
168                    even if it hasn't changed itself.
169        */
170        virtual void _update(bool updateChildren, bool parentHasChanged);
171
172                /** Tells the SceneNode to update the world bound info it stores.
173                */
174                virtual void _updateBounds(void);
175
176        /** Internal method which locates any visible objects attached to this node and adds them to the passed in queue.
177            @remarks
178                Should only be called by a SceneManager implementation, and only after the _updat method has been called to
179                ensure transforms and world bounds are up to date.
180                SceneManager implementations can choose to let the search cascade automatically, or choose to prevent this
181                and select nodes themselves based on some other criteria.
182            @param
183                cam The active camera
184            @param
185                queue The SceneManager's rendering queue
186            @param
187                includeChildren If true, the call is cascaded down to all child nodes automatically.
188            @param
189                displayNodes If true, the nodes themselves are rendered as a set of 3 axes as well
190                    as the objects being rendered. For debugging purposes.
191        */
192        virtual void _findVisibleObjects(Camera* cam, RenderQueue* queue,
193            bool includeChildren = true, bool displayNodes = false, bool onlyShadowCasters = false);
194
195        /** Gets the axis-aligned bounding box of this node (and hence all subnodes).
196        @remarks
197            Recommended only if you are extending a SceneManager, because the bounding box returned
198            from this method is only up to date after the SceneManager has called _update.
199        */
200        virtual const AxisAlignedBox& _getWorldAABB(void) const;
201
202        /** Retrieves an iterator which can be used to efficiently step through the objects
203            attached to this node.
204        @remarks
205            This is a much faster way to go through <B>all</B> the objects attached to the node
206            than using getAttachedObject. But the iterator returned is only valid until a change
207            is made to the collection (ie an addition or removal) so treat the returned iterator
208            as transient, and don't add / remove items as you go through the iterator, save changes
209            until the end, or retrieve a new iterator after making the change. Making changes to
210            the object returned through the iterator is OK though.
211        */
212        virtual ObjectIterator getAttachedObjectIterator(void);
213        /** Retrieves an iterator which can be used to efficiently step through the objects
214            attached to this node.
215        @remarks
216            This is a much faster way to go through <B>all</B> the objects attached to the node
217            than using getAttachedObject. But the iterator returned is only valid until a change
218            is made to the collection (ie an addition or removal) so treat the returned iterator
219            as transient, and don't add / remove items as you go through the iterator, save changes
220            until the end, or retrieve a new iterator after making the change. Making changes to
221            the object returned through the iterator is OK though.
222        */
223                virtual ConstObjectIterator getAttachedObjectIterator(void) const;
224
225        /** Gets the creator of this scene node.
226        @remarks
227            This method returns the SceneManager which created this node.
228            This can be useful for destroying this node.
229        */
230        SceneManager* getCreator(void) const;
231
232        /** This method removes and destroys the named child and all of its children.
233        @remarks
234            Unlike removeChild, which removes a single named child from this
235            node but does not destroy it, this method destroys the child
236            and all of it's children.
237        @par
238            Use this if you wish to recursively destroy a node as well as
239            detaching it from it's parent. Note that any objects attached to
240            the nodes will be detached but will not themselves be destroyed.
241        */
242        virtual void removeAndDestroyChild(const String& name);
243
244        /** This method removes and destroys the child and all of its children.
245        @remarks
246            Unlike removeChild, which removes a single named child from this
247            node but does not destroy it, this method destroys the child
248            and all of it's children.
249        @par
250            Use this if you wish to recursively destroy a node as well as
251            detaching it from it's parent. Note that any objects attached to
252            the nodes will be detached but will not themselves be destroyed.
253        */
254        virtual void removeAndDestroyChild(unsigned short index);
255
256        /** Removes and destroys all children of this node.
257        @remarks
258            Use this to destroy all child nodes of this node and remove
259            them from the scene graph. Note that all objects attached to this
260            node will be detached but will not be destroyed.
261        */
262        virtual void removeAndDestroyAllChildren(void);
263
264        /** Allows the showing of the node's bounding box.
265        @remarks
266            Use this to show or hide the bounding box of the node.
267        */
268                virtual void showBoundingBox(bool bShow);
269
270        /** Add the bounding box to the rendering queue.
271        */
272                virtual void _addBoundingBoxToQueue(RenderQueue* queue);
273
274        /** This allows scene managers to determine if the node's bounding box
275                        should be added to the rendering queue.
276        @remarks
277            Scene Managers that implement their own _findVisibleObjects will have to
278                        check this flag and then use _addBoundingBoxToQueue to add the bounding box
279                        wireframe.
280        */
281                virtual bool getShowBoundingBox() const;
282
283        /** Creates an unnamed new SceneNode as a child of this node.
284        @param
285            translate Initial translation offset of child relative to parent
286        @param
287            rotate Initial rotation relative to parent
288        */
289        virtual SceneNode* createChildSceneNode(
290            const Vector3& translate = Vector3::ZERO,
291            const Quaternion& rotate = Quaternion::IDENTITY );
292
293        /** Creates a new named SceneNode as a child of this node.
294        @remarks
295            This creates a child node with a given name, which allows you to look the node up from
296            the parent which holds this collection of nodes.
297            @param
298                translate Initial translation offset of child relative to parent
299            @param
300                rotate Initial rotation relative to parent
301        */
302        virtual SceneNode* createChildSceneNode(const String& name, const Vector3& translate = Vector3::ZERO, const Quaternion& rotate = Quaternion::IDENTITY);
303
304        /** Allows retrieval of the nearest lights to the centre of this SceneNode.
305        @remarks
306            This method allows a list of lights, ordered by proximity to the centre of
307            this SceneNode, to be retrieved. Multiple access to this method when neither
308            the node nor the lights have moved will result in the same list being returned
309            without recalculation. Can be useful when implementing Renderable::getLights.
310        @param radius Optional parameter to specify lights intersecting a given radius of
311            this SceneNode's centre.
312        */
313        virtual const LightList& findLights(Real radius) const;
314
315        /** Tells the node whether to yaw around it's own local Y axis or a fixed axis of choice.
316        @remarks
317        This method allows you to change the yaw behaviour of the node - by default, it
318        yaws around it's own local Y axis when told to yaw with TS_LOCAL, this makes it
319        yaw around a fixed axis.
320        You only really need this when you're using auto tracking (see setAutoTracking,
321        because when you're manually rotating a node you can specify the TransformSpace
322        in which you wish to work anyway.
323        @param
324        useFixed If true, the axis passed in the second parameter will always be the yaw axis no
325        matter what the node orientation. If false, the node returns to it's default behaviour.
326        @param
327        fixedAxis The axis to use if the first parameter is true.
328        */
329        virtual void setFixedYawAxis( bool useFixed, const Vector3& fixedAxis = Vector3::UNIT_Y );
330
331                /** Rotate the node around the Y-axis.
332                */
333                virtual void yaw(const Radian& angle, TransformSpace relativeTo = TS_LOCAL);
334#ifndef OGRE_FORCE_ANGLE_TYPES
335                inline void yaw(Real degrees, TransformSpace relativeTo = TS_LOCAL) {
336                        yaw ( Angle(degrees), relativeTo );
337                }
338#endif//OGRE_FORCE_ANGLE_TYPES
339        /** Sets the node's direction vector ie it's local -z.
340        @remarks
341        Note that the 'up' vector for the orientation will automatically be
342        recalculated based on the current 'up' vector (i.e. the roll will
343        remain the same). If you need more control, use setOrientation.
344        @param x,y,z The components of the direction vector
345        @param relativeTo The space in which this direction vector is expressed
346        @param localDirectionVector The vector which normally describes the natural
347        direction of the node, usually -Z
348        */
349        virtual void setDirection(Real x, Real y, Real z,
350            TransformSpace relativeTo = TS_LOCAL,
351            const Vector3& localDirectionVector = Vector3::NEGATIVE_UNIT_Z);
352
353        /** Sets the node's direction vector ie it's local -z.
354        @remarks
355        Note that the 'up' vector for the orientation will automatically be
356        recalculated based on the current 'up' vector (i.e. the roll will
357        remain the same). If you need more control, use setOrientation.
358        @param vec The direction vector
359        @param relativeTo The space in which this direction vector is expressed
360        @param localDirectionVector The vector which normally describes the natural
361        direction of the node, usually -Z
362        */
363        virtual void setDirection(const Vector3& vec, TransformSpace relativeTo = TS_LOCAL,
364            const Vector3& localDirectionVector = Vector3::NEGATIVE_UNIT_Z);
365        /** Points the local -Z direction of this node at a point in space.
366        @param targetPoint A vector specifying the look at point.
367        @param relativeTo The space in which the point resides
368        @param localDirectionVector The vector which normally describes the natural
369        direction of the node, usually -Z
370        */
371        virtual void lookAt( const Vector3& targetPoint, TransformSpace relativeTo,
372            const Vector3& localDirectionVector = Vector3::NEGATIVE_UNIT_Z);
373        /** Enables / disables automatic tracking of another SceneNode.
374        @remarks
375        If you enable auto-tracking, this SceneNode will automatically rotate to
376        point it's -Z at the target SceneNode every frame, no matter how
377        it or the other SceneNode move. Note that by default the -Z points at the
378        origin of the target SceneNode, if you want to tweak this, provide a
379        vector in the 'offset' parameter and the target point will be adjusted.
380        @param enabled If true, tracking will be enabled and the next
381        parameter cannot be null. If false tracking will be disabled and the
382        current orientation will be maintained.
383        @param target Pointer to the SceneNode to track. Make sure you don't
384        delete this SceneNode before turning off tracking (e.g. SceneManager::clearScene will
385        delete it so be careful of this). Can be null if and only if the enabled param is false.
386        @param localDirectionVector The local vector considered to be the usual 'direction'
387        of the node; normally the local -Z but can be another direction.
388        @param offset If supplied, this is the target point in local space of the target node
389        instead of the origin of the target node. Good for fine tuning the look at point.
390        */
391        virtual void setAutoTracking(bool enabled, SceneNode* target = 0,
392            const Vector3& localDirectionVector = Vector3::NEGATIVE_UNIT_Z,
393            const Vector3& offset = Vector3::ZERO);
394                /** Get the auto tracking target for this node, if any. */
395        virtual SceneNode* getAutoTrackTarget(void) { return mAutoTrackTarget; }
396                /** Get the auto tracking offset for this node, if the node is auto tracking. */
397                virtual const Vector3& getAutoTrackOffset(void) { return mAutoTrackOffset; }
398                /** Get the auto tracking local direction for this node, if it is auto tracking. */
399                virtual const Vector3& getAutoTrackLocalDirection(void) { return mAutoTrackLocalDirection; }
400                /** Internal method used by OGRE to update auto-tracking cameras. */
401        void _autoTrack(void);
402        /** Gets the parent of this SceneNode. */
403        SceneNode* getParentSceneNode(void) const;
404        /** Makes all objects attached to this node become visible / invisble.
405        @remarks   
406            This is a shortcut to calling setVisible() on the objects attached
407            to this node, and optionally to all objects attached to child
408            nodes.
409        @param visible Whether the objects are to be made visible or invisible
410        @param cascade If true, this setting cascades into child nodes too.
411        */
412        virtual void setVisible(bool visible, bool cascade = true);
413        /** Inverts the visibility of all objects attached to this node.
414        @remarks   
415        This is a shortcut to calling setVisible(!isVisible()) on the objects attached
416        to this node, and optionally to all objects attached to child
417        nodes.
418        @param cascade If true, this setting cascades into child nodes too.
419        */
420        virtual void flipVisibility(bool cascade = true);
421
422
423
424
425
426    };
427
428
429}// namespace
430
431#endif
Note: See TracBrowser for help on using the repository browser.