doxygen: gameengine/SceneGraph tagged.
[blender.git] / source / gameengine / SceneGraph / SG_ParentRelation.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
31 /** \file SG_ParentRelation.h
32  *  \ingroup bgesg
33  * @page SG_ParentRelationPage SG_ParentRelation   
34
35  * @section SG_ParentRelationSection SG_ParentRelation
36  * 
37  * This is an abstract interface class to the Scene Graph library. 
38  * It allows you to specify how child nodes react to parent nodes.
39  * Normally a child will use it's parent's transforms to compute
40  * it's own global transforms. How this is performed depends on
41  * the type of relation. For example if the parent is a vertex 
42  * parent to this child then the child should not inherit any 
43  * rotation information from the parent. Or if the parent is a
44  * 'slow parent' to this child then the child should react 
45  * slowly to changes in the parent's position. The exact relation
46  * is left for you to implement by filling out this interface 
47  * with concrete examples. 
48  * 
49  * There is exactly one SG_ParentRelation per SG_Node. Subclasses
50  * should not be value types and should be allocated on the heap.
51  *
52  */
53  
54 #ifndef __SG_ParentRelation_h
55 #define __SG_ParentRelation_h
56
57 class SG_Spatial;
58
59 class SG_ParentRelation {
60
61 public :
62         /**
63          * Update the childs local and global coordinates
64          * based upon the parents global coordinates. 
65          * You must also handle the case when this node has no
66          * parent (parent == NULL). Usually you should just 
67          * copy the local coordinates of the child to the 
68          * world coordinates.
69          */ 
70         
71         virtual
72                 bool
73         UpdateChildCoordinates(
74                 SG_Spatial * child,
75                 const SG_Spatial * parent,
76                 bool& parentUpdated
77         ) = 0;
78
79         virtual 
80         ~SG_ParentRelation(
81         ){
82         };
83
84         /** 
85          * You must provide a way of duplicating an
86          * instance of an SG_ParentRelation. This should
87          * return a pointer to a new duplicate allocated
88          * on the heap. Responsibilty for deleting the 
89          * duplicate resides with the caller of this method.
90          */
91
92         virtual 
93                 SG_ParentRelation *
94         NewCopy(
95         ) = 0;
96
97         /**
98          * Vertex Parent Relation are special: they don't propagate rotation
99          */
100         virtual
101                 bool
102         IsVertexRelation(
103         ) { 
104                 return false;
105         }
106         
107         /**
108          * Need this to see if we are able to adjust time-offset from the python api
109          */
110         virtual
111                 bool
112         IsSlowRelation(
113         ) { 
114                 return false;
115         }
116 protected :
117
118         /** 
119          * Protected constructors 
120          * this class is not meant to be instantiated.
121          */
122
123         SG_ParentRelation(
124         ) {     
125         };
126
127         /**
128          * Copy construction should not be implemented
129          */
130
131         SG_ParentRelation(
132                 const SG_ParentRelation &
133         ); 
134         
135         
136 #ifdef WITH_CXX_GUARDEDALLOC
137 public:
138         void *operator new(size_t num_bytes) { return MEM_mallocN(num_bytes, "GE:SG_ParentRelation"); }
139         void operator delete( void *mem ) { MEM_freeN(mem); }
140 #endif
141 };      
142
143 #endif
144