fix a scanf warning
[divverent/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   {
40     return *nullInstancePointer;
41   }
42
43   class Node;
44   const Node* const nullNodePointer = 0;
45   inline const Node& nullNode()
46   {
47     return *nullNodePointer;
48   }
49 }
50
51 typedef Reference<scene::Node> NodeReference;
52
53 typedef std::size_t TypeId;
54
55 const TypeId NODETYPEID_MAX = 64;
56 const TypeId NODETYPEID_NONE = NODETYPEID_MAX;
57
58 const TypeId INSTANCETYPEID_MAX = 64;
59 const TypeId INSTANCETYPEID_NONE = INSTANCETYPEID_MAX;
60
61 namespace scene
62 {
63   /// \brief A unique key to an instance of a node in the scene-graph.
64   typedef Stack<NodeReference> Path;
65
66   /// \brief A scene-graph - a Directed Acyclic Graph (DAG).
67   ///
68   /// - Each node may refer to zero or more 'child' nodes (directed).
69   /// - A node may never have itself as one of its ancestors (acyclic).
70   /// - Each node may have more than one 'parent', thus having more than one 'instance' in the graph.
71   /// - Each instance is uniquely identified by the list of its ancestors plus itself, known as a 'path'.
72   class Graph
73   {
74   public:
75     INTEGER_CONSTANT(Version, 1);
76     STRING_CONSTANT(Name, "scenegraph");
77
78     class Walker
79     {
80     public:
81       /// \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.
82       virtual bool pre(const Path& path, Instance& instance) const = 0;
83       /// \brief Called after traversing the last child-instance of 'instance'.
84       virtual void post(const Path& path, Instance& instance) const
85       {
86       }
87     };
88
89     /// \brief Returns the root-node of the graph.
90     virtual Node& root() = 0;
91     /// \brief Sets the root-node of the graph to be 'node'.
92     virtual void insert_root(Node& root) = 0;
93     /// \brief Clears the root-node of the graph.
94     virtual void erase_root() = 0;
95     /// \brief Traverses all nodes in the graph depth-first, starting from the root node.
96     virtual void traverse(const Walker& walker) = 0;
97     /// \brief Traverses all nodes in the graph depth-first, starting from 'start'.
98     virtual void traverse_subgraph(const Walker& walker, const Path& start) = 0;
99     /// \brief Returns the instance at the location identified by 'path', or 0 if it does not exist.
100     virtual scene::Instance* find(const Path& path) = 0;
101
102     /// \brief Invokes all scene-changed callbacks. Called when any part of the scene changes the way it will appear when the scene is rendered.
103     /// \todo Move to a separate class.
104     virtual void sceneChanged() = 0;
105     /// \brief Add a \p callback to be invoked when the scene changes.
106     /// \todo Move to a separate class.
107     virtual void addSceneChangedCallback(const SignalHandler& handler) = 0;
108
109     /// \brief Invokes all bounds-changed callbacks. Called when the bounds of any instance in the scene change.
110     /// \todo Move to a separate class.
111     virtual void boundsChanged() = 0;
112     /// \brief Add a \p callback to be invoked when the bounds of any instance in the scene change.
113     virtual SignalHandlerId addBoundsChangedCallback(const SignalHandler& boundsChanged) = 0;
114     /// \brief Remove a \p callback to be invoked when the bounds of any instance in the scene change.
115     virtual void removeBoundsChangedCallback(SignalHandlerId id) = 0;
116
117     virtual TypeId getNodeTypeId(const char* name) = 0;
118     virtual TypeId getInstanceTypeId(const char* name) = 0;
119   };
120
121   class Traversable
122   {
123   public:
124     STRING_CONSTANT(Name, "scene::Traversable");
125
126     class Observer
127     {
128     public:
129       /// \brief Called when a node is added to the container.
130       virtual void insert(Node& node) = 0;
131       /// \brief Called when a node is removed from the container.
132       virtual void erase(Node& node) = 0;
133     };
134
135     class Walker
136     {
137     public:
138       /// \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.
139       virtual bool pre(Node& node) const = 0;
140       /// \brief Called after traversing the last child-node of 'node'. 
141       virtual void post(Node& node) const
142       {
143       }
144     };
145     /// \brief Adds a node to the container.
146     virtual void insert(Node& node) = 0;
147     /// \brief Removes a node from the container.
148     virtual void erase(Node& node) = 0;
149     /// \brief Traverses the subgraphs rooted at each node in the container, depth-first.
150     virtual void traverse(const Walker& walker) = 0;
151     /// \brief Returns true if the container contains no nodes.
152     virtual bool empty() const = 0;
153   };
154
155   class Instantiable
156   {
157   public:
158     STRING_CONSTANT(Name, "scene::Instantiable");
159
160     class Observer
161     {
162     public:
163       /// \brief Called when an instance is added to the container.
164       virtual void insert(scene::Instance* instance) = 0;
165       /// \brief Called when an instance is removed from the container.
166       virtual void erase(scene::Instance* instance) = 0;
167     };
168
169     class Visitor
170     {
171     public:
172       virtual void visit(Instance& instance) const = 0;
173     };
174
175     /// \brief Returns a new instance uniquely identified by 'path'.
176     virtual scene::Instance* create(const scene::Path& path, scene::Instance* parent) = 0;
177     /// \brief Calls Visitor::visit(instance) for each instance in the container.
178     virtual void forEachInstance(const Visitor& visitor) = 0;
179     /// \brief Adds an instance to the container.
180     virtual void insert(Observer* observer, const Path& path, scene::Instance* instance) = 0;
181     /// \brief Returns an instance removed from the container.
182     virtual scene::Instance* erase(Observer* observer, const Path& path) = 0;
183   };
184
185   class Cloneable
186   {
187   public:
188     STRING_CONSTANT(Name, "scene::Cloneable");
189
190     /// \brief Returns a copy of itself.
191     virtual scene::Node& clone() const = 0;
192   };
193 }
194
195 #include "modulesystem.h"
196
197 template<typename Type>
198 class GlobalModule;
199 typedef GlobalModule<scene::Graph> GlobalSceneGraphModule;
200
201 template<typename Type>
202 class GlobalModuleRef;
203 typedef GlobalModuleRef<scene::Graph> GlobalSceneGraphModuleRef;
204
205 inline scene::Graph& GlobalSceneGraph()
206 {
207   return GlobalSceneGraphModule::getTable();
208 }
209
210 inline void AddSceneChangeCallback(const SignalHandler& handler)
211 {
212   GlobalSceneGraph().addSceneChangedCallback(handler);
213 }
214 inline void SceneChangeNotify()
215 {
216   GlobalSceneGraph().sceneChanged();
217 }
218
219
220
221 #endif