Merge remote-tracking branch 'illwieckz/pakpath'
[xonotic/netradiant.git] / include / iscenegraph.h
1 /*
2    Copyright (C) 2001-2006, William Joseph.
3    All Rights Reserved.
4
5    This file is part of GtkRadiant.
6
7    GtkRadiant is free software; you can redistribute it and/or modify
8    it under the terms of the GNU General Public License as published by
9    the Free Software Foundation; either version 2 of the License, or
10    (at your option) any later version.
11
12    GtkRadiant is distributed in the hope that it will be useful,
13    but WITHOUT ANY WARRANTY; without even the implied warranty of
14    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
15    GNU General Public License for more details.
16
17    You should have received a copy of the GNU General Public License
18    along with GtkRadiant; if not, write to the Free Software
19    Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA  02110-1301  USA
20  */
21
22 #if !defined ( INCLUDED_ISCENEGRAPH_H )
23 #define INCLUDED_ISCENEGRAPH_H
24
25 #include <cstddef>
26 #include "generic/constant.h"
27 #include "signal/signalfwd.h"
28
29 template<typename value_type>
30 class Stack;
31 template<typename Contained>
32 class Reference;
33
34 namespace scene
35 {
36 class Instance;
37 const Instance* const nullInstancePointer = 0;
38 inline const Instance& nullInstance(){
39         return *nullInstancePointer;
40 }
41
42 class Node;
43 const Node* const nullNodePointer = 0;
44 inline const Node& nullNode(){
45         return *nullNodePointer;
46 }
47 }
48
49 typedef Reference<scene::Node> NodeReference;
50
51 typedef std::size_t TypeId;
52
53 const TypeId NODETYPEID_MAX = 64;
54 const TypeId NODETYPEID_NONE = NODETYPEID_MAX;
55
56 const TypeId INSTANCETYPEID_MAX = 64;
57 const TypeId INSTANCETYPEID_NONE = INSTANCETYPEID_MAX;
58
59 namespace scene
60 {
61 /// \brief A unique key to an instance of a node in the scene-graph.
62 typedef Stack<NodeReference> Path;
63
64 /// \brief A scene-graph - a Directed Acyclic Graph (DAG).
65 ///
66 /// - Each node may refer to zero or more 'child' nodes (directed).
67 /// - A node may never have itself as one of its ancestors (acyclic).
68 /// - Each node may have more than one 'parent', thus having more than one 'instance' in the graph.
69 /// - Each instance is uniquely identified by the list of its ancestors plus itself, known as a 'path'.
70 class Graph
71 {
72 public:
73 INTEGER_CONSTANT( Version, 1 );
74 STRING_CONSTANT( Name, "scenegraph" );
75
76 class Walker
77 {
78 public:
79 /// \brief Called before traversing the first child-instance of 'instance'. If the return value is false, the children of the current instance are not traversed.
80 virtual bool pre( const Path& path, Instance& instance ) const = 0;
81 /// \brief Called after traversing the last child-instance of 'instance'.
82 virtual void post( const Path& path, Instance& instance ) const {
83 }
84 };
85
86 /// \brief Returns the root-node of the graph.
87 virtual Node& root() = 0;
88 /// \brief Sets the root-node of the graph to be 'node'.
89 virtual void insert_root( Node& root ) = 0;
90 /// \brief Clears the root-node of the graph.
91 virtual void erase_root() = 0;
92 /// \brief Traverses all nodes in the graph depth-first, starting from the root node.
93 virtual void traverse( const Walker& walker ) = 0;
94 /// \brief Traverses all nodes in the graph depth-first, starting from 'start'.
95 virtual void traverse_subgraph( const Walker& walker, const Path& start ) = 0;
96 /// \brief Returns the instance at the location identified by 'path', or 0 if it does not exist.
97 virtual scene::Instance* find( const Path& path ) = 0;
98
99 /// \brief Invokes all scene-changed callbacks. Called when any part of the scene changes the way it will appear when the scene is rendered.
100 /// \todo Move to a separate class.
101 virtual void sceneChanged() = 0;
102 /// \brief Add a \p callback to be invoked when the scene changes.
103 /// \todo Move to a separate class.
104 virtual void addSceneChangedCallback( const SignalHandler& handler ) = 0;
105
106 /// \brief Invokes all bounds-changed callbacks. Called when the bounds of any instance in the scene change.
107 /// \todo Move to a separate class.
108 virtual void boundsChanged() = 0;
109 /// \brief Add a \p callback to be invoked when the bounds of any instance in the scene change.
110 virtual SignalHandlerId addBoundsChangedCallback( const SignalHandler& boundsChanged ) = 0;
111 /// \brief Remove a \p callback to be invoked when the bounds of any instance in the scene change.
112 virtual void removeBoundsChangedCallback( SignalHandlerId id ) = 0;
113
114 virtual TypeId getNodeTypeId( const char* name ) = 0;
115 virtual TypeId getInstanceTypeId( const char* name ) = 0;
116 };
117
118 class Traversable
119 {
120 public:
121 STRING_CONSTANT( Name, "scene::Traversable" );
122
123 class Observer
124 {
125 public:
126 /// \brief Called when a node is added to the container.
127 virtual void insert( Node& node ) = 0;
128 /// \brief Called when a node is removed from the container.
129 virtual void erase( Node& node ) = 0;
130 };
131
132 class Walker
133 {
134 public:
135 /// \brief Called before traversing the first child-node of 'node'. If the return value is false, the children of the current node are not traversed.
136 virtual bool pre( Node& node ) const = 0;
137 /// \brief Called after traversing the last child-node of 'node'.
138 virtual void post( Node& node ) const {
139 }
140 };
141 /// \brief Adds a node to the container.
142 virtual void insert( Node& node ) = 0;
143 /// \brief Removes a node from the container.
144 virtual void erase( Node& node ) = 0;
145 /// \brief Traverses the subgraphs rooted at each node in the container, depth-first.
146 virtual void traverse( const Walker& walker ) = 0;
147 /// \brief Returns true if the container contains no nodes.
148 virtual bool empty() const = 0;
149 };
150
151 class Instantiable
152 {
153 public:
154 STRING_CONSTANT( Name, "scene::Instantiable" );
155
156 class Observer
157 {
158 public:
159 /// \brief Called when an instance is added to the container.
160 virtual void insert( scene::Instance* instance ) = 0;
161 /// \brief Called when an instance is removed from the container.
162 virtual void erase( scene::Instance* instance ) = 0;
163 };
164
165 class Visitor
166 {
167 public:
168 virtual void visit( Instance& instance ) const = 0;
169 };
170
171 /// \brief Returns a new instance uniquely identified by 'path'.
172 virtual scene::Instance* create( const scene::Path& path, scene::Instance* parent ) = 0;
173 /// \brief Calls Visitor::visit(instance) for each instance in the container.
174 virtual void forEachInstance( const Visitor& visitor ) = 0;
175 /// \brief Adds an instance to the container.
176 virtual void insert( Observer* observer, const Path& path, scene::Instance* instance ) = 0;
177 /// \brief Returns an instance removed from the container.
178 virtual scene::Instance* erase( Observer* observer, const Path& path ) = 0;
179 };
180
181 class Cloneable
182 {
183 public:
184 STRING_CONSTANT( Name, "scene::Cloneable" );
185
186 /// \brief Returns a copy of itself.
187 virtual scene::Node& clone() const = 0;
188 };
189 }
190
191 #include "modulesystem.h"
192
193 template<typename Type>
194 class GlobalModule;
195 typedef GlobalModule<scene::Graph> GlobalSceneGraphModule;
196
197 template<typename Type>
198 class GlobalModuleRef;
199 typedef GlobalModuleRef<scene::Graph> GlobalSceneGraphModuleRef;
200
201 inline scene::Graph& GlobalSceneGraph(){
202         return GlobalSceneGraphModule::getTable();
203 }
204
205 inline void AddSceneChangeCallback( const SignalHandler& handler ){
206         GlobalSceneGraph().addSceneChangedCallback( handler );
207 }
208 inline void SceneChangeNotify(){
209         GlobalSceneGraph().sceneChanged();
210 }
211
212
213
214 #endif