copy of docs from 2.4x for python modules that have been kept
[blender.git] / source / gameengine / SceneGraph / SG_ParentRelation.h
1 /**
2  * @mainpage SG_ParentRelation   
3
4  * @section 
5  * 
6  * This is an abstract interface class to the Scene Graph library. 
7  * It allows you to specify how child nodes react to parent nodes.
8  * Normally a child will use it's parent's transforms to compute
9  * it's own global transforms. How this is performed depends on
10  * the type of relation. For example if the parent is a vertex 
11  * parent to this child then the child should not inherit any 
12  * rotation information from the parent. Or if the parent is a
13  * 'slow parent' to this child then the child should react 
14  * slowly to changes in the parent's position. The exact relation
15  * is left for you to implement by filling out this interface 
16  * with concrete examples. 
17  * 
18  * There is exactly one SG_ParentRelation per SG_Node. Subclasses
19  * should not be value types and should be allocated on the heap.
20  *
21  * $Id$
22  *
23  * ***** BEGIN GPL LICENSE BLOCK *****
24  *
25  * This program is free software; you can redistribute it and/or
26  * modify it under the terms of the GNU General Public License
27  * as published by the Free Software Foundation; either version 2
28  * of the License, or (at your option) any later version.
29  *
30  * This program is distributed in the hope that it will be useful,
31  * but WITHOUT ANY WARRANTY; without even the implied warranty of
32  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
33  * GNU General Public License for more details.
34  *
35  * You should have received a copy of the GNU General Public License
36  * along with this program; if not, write to the Free Software Foundation,
37  * Inc., 59 Temple Place - Suite 330, Boston, MA  02111-1307, USA.
38  *
39  * The Original Code is Copyright (C) 2001-2002 by NaN Holding BV.
40  * All rights reserved.
41  *
42  * The Original Code is: all of this file.
43  *
44  * Contributor(s): none yet.
45  *
46  * ***** END GPL LICENSE BLOCK *****
47  * 
48  */
49
50 #ifndef __SG_ParentRelation_h
51 #define __SG_ParentRelation_h
52
53 class SG_Spatial;
54
55 class SG_ParentRelation {
56
57 public :
58         /**
59          * Update the childs local and global coordinates
60          * based upon the parents global coordinates. 
61          * You must also handle the case when this node has no
62          * parent (parent == NULL). Usually you should just 
63          * copy the local coordinates of the child to the 
64          * world coordinates.
65          */ 
66         
67         virtual
68                 bool
69         UpdateChildCoordinates(
70                 SG_Spatial * child,
71                 const SG_Spatial * parent,
72                 bool& parentUpdated
73         ) = 0;
74
75         virtual 
76         ~SG_ParentRelation(
77         ){
78         };
79
80         /** 
81          * You must provide a way of duplicating an
82          * instance of an SG_ParentRelation. This should
83          * return a pointer to a new duplicate allocated
84          * on the heap. Responsibilty for deleting the 
85          * duplicate resides with the caller of this method.
86          */
87
88         virtual 
89                 SG_ParentRelation *
90         NewCopy(
91         ) = 0;
92
93         /**
94          * Vertex Parent Relation are special: they don't propagate rotation
95          */
96         virtual
97                 bool
98         IsVertexRelation(
99         ) { 
100                 return false;
101         }
102         
103         /**
104          * Need this to see if we are able to adjust time-offset from the python api
105          */
106         virtual
107                 bool
108         IsSlowRelation(
109         ) { 
110                 return false;
111         }
112 protected :
113
114         /** 
115          * Protected constructors 
116          * this class is not meant to be instantiated.
117          */
118
119         SG_ParentRelation(
120         ) {     
121         };
122
123         /**
124          * Copy construction should not be implemented
125          */
126
127         SG_ParentRelation(
128                 const SG_ParentRelation &
129         ); 
130         
131         
132 #ifdef WITH_CXX_GUARDEDALLOC
133 public:
134         void *operator new( unsigned int num_bytes) { return MEM_mallocN(num_bytes, "GE:SG_ParentRelation"); }
135         void operator delete( void *mem ) { MEM_freeN(mem); }
136 #endif
137 };      
138
139 #endif
140