doxygen: bge scenegraph and videotexture
[blender-staging.git] / source / gameengine / SceneGraph / SG_Node.h
1 /*
2  * $Id$
3  *
4  * ***** BEGIN GPL LICENSE BLOCK *****
5  *
6  * This program is free software; you can redistribute it and/or
7  * modify it under the terms of the GNU General Public License
8  * as published by the Free Software Foundation; either version 2
9  * of the License, or (at your option) any later version.
10  *
11  * This program is distributed in the hope that it will be useful,
12  * but WITHOUT ANY WARRANTY; without even the implied warranty of
13  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
14  * GNU General Public License for more details.
15  *
16  * You should have received a copy of the GNU General Public License
17  * along with this program; if not, write to the Free Software Foundation,
18  * Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
19  *
20  * The Original Code is Copyright (C) 2001-2002 by NaN Holding BV.
21  * All rights reserved.
22  *
23  * The Original Code is: all of this file.
24  *
25  * Contributor(s): none yet.
26  *
27  * ***** END GPL LICENSE BLOCK *****
28  */
29
30 /** \file SG_Node.h
31  *  \ingroup bgesg
32  */
33  
34 #ifndef __SG_NODE_H
35 #define __SG_NODE_H
36
37 #include "SG_Spatial.h"
38 #include <vector>
39
40 typedef std::vector<SG_Node*> NodeList;
41
42 /**
43  * Scenegraph node.
44  */
45 class SG_Node : public SG_Spatial
46 {
47 public:
48         SG_Node(
49                 void* clientobj,
50                 void* clientinfo,
51                 SG_Callbacks& callbacks
52         );
53
54         SG_Node(
55                 const SG_Node & other
56         );
57
58         virtual ~SG_Node();
59
60
61         /**
62          * Add a child to this object. This also informs the child of
63          * it's parent.
64          * This just stores a pointer to the child and does not
65          * make a deep copy.
66          */
67
68                 void    
69         AddChild(
70                 SG_Node* child
71         );
72
73         /** 
74          * Remove a child node from this object. This just removes the child
75          * pointer from the list of children - it does not destroy the child.
76          * This does not inform the child that this node is no longer it's parent.
77          * If the node was not a child of this object no action is performed.
78          */
79
80                 void    
81         RemoveChild(
82                 SG_Node* child
83         );
84
85         /**
86          * Return true if the node is the ancessor of child
87          */
88                 bool
89         IsAncessor(
90                 const SG_Node* child
91         ) const;
92         /** 
93          * Get the current list of children. Do not use this interface for
94          * adding or removing children please use the methods of this class for
95          * that.
96          * @return a reference to the list of children of this node.
97          */
98         
99         NodeList& GetSGChildren()
100         {
101                 return this->m_children;
102         }
103
104         /**
105          * Get the current list of children.
106          * @return a const reference to the current list of children of this node.
107          */
108
109         const NodeList& GetSGChildren() const
110         {
111                 return this->m_children;
112         }
113
114         /** 
115          * Clear the list of children associated with this node
116          */
117
118         void ClearSGChildren()
119         {
120                 m_children.clear();
121         }
122
123         /**
124          * return the parent of this node if it exists.
125          */
126                 
127         SG_Node* GetSGParent() const 
128         { 
129                 return m_SGparent;
130         }
131
132         /**
133          * Set the parent of this node. 
134          */
135
136         void SetSGParent(SG_Node* parent)
137         {
138                 m_SGparent = parent;
139         }
140
141         /**
142          * Return the top node in this node's Scene graph hierarchy
143          */
144         
145         const 
146                 SG_Node* 
147         GetRootSGParent(
148         ) const;
149
150         /**
151          * Disconnect this node from it's parent
152          */
153
154                 void                            
155         DisconnectFromParent(
156         );
157
158         /**
159          * Return vertex parent status.
160          */
161         bool IsVertexParent()
162         {
163                 if (m_parent_relation)
164                 {
165                         return m_parent_relation->IsVertexRelation();
166                 }
167                 return false;
168         }
169
170
171         /**
172          * Return slow parent status.
173          */
174
175         bool IsSlowParent()
176         {
177                 if (m_parent_relation)
178                 {
179                         return m_parent_relation->IsSlowRelation();
180                 }
181                 return false;
182         }
183
184
185
186
187         /**             
188          * Update the spatial data of this node. Iterate through
189          * the children of this node and update their world data.
190          */
191
192                 void            
193         UpdateWorldData(
194                 double time,
195                 bool parentUpdated=false
196         );
197
198         /**
199          * Update the simulation time of this node. Iterate through
200          * the children nodes and update their simulated time.
201          */
202
203                 void            
204         SetSimulatedTime(
205                 double time,
206                 bool recurse
207         );
208
209         /**
210          * Schedule this node for update by placing it in head queue
211          */
212         bool Schedule(SG_QList& head)
213         {
214                 // Put top parent in front of list to make sure they are updated before their
215                 // children => the children will be udpated and removed from the list before
216                 // we get to them, should they be in the list too.
217                 return (m_SGparent)?head.AddBack(this):head.AddFront(this);
218         }
219
220         /**
221          * Used during Scenegraph update
222          */
223         static SG_Node* GetNextScheduled(SG_QList& head)
224         {
225                 return static_cast<SG_Node*>(head.Remove());
226         }
227
228         /**
229          * Make this node ready for schedule on next update. This is needed for nodes
230          * that must always be updated (slow parent, bone parent)
231          */
232         bool Reschedule(SG_QList& head)
233         {
234                 return head.QAddBack(this);
235         }
236
237         /**
238          * Used during Scenegraph update
239          */
240         static SG_Node* GetNextRescheduled(SG_QList& head)
241         {
242                 return static_cast<SG_Node*>(head.QRemove());
243         }
244
245         /**
246          * Node replication functions.
247          */
248
249                 SG_Node*        
250         GetSGReplica(
251         );
252
253                 void            
254         Destruct(
255         );
256         
257 private:
258
259                 void            
260         ProcessSGReplica(
261                 SG_Node** replica
262         );
263
264         /**
265          * The list of children of this node.
266          */
267         NodeList m_children;
268
269         /**
270          * The parent of this node may be NULL
271          */
272         SG_Node* m_SGparent;
273
274
275 #ifdef WITH_CXX_GUARDEDALLOC
276 public:
277         void *operator new(size_t num_bytes) { return MEM_mallocN(num_bytes, "GE:SG_Node"); }
278         void operator delete( void *mem ) { MEM_freeN(mem); }
279 #endif
280 };
281
282 #endif //__SG_NODE_H
283