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 virtual ~Walker(){}
  80 /// \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.
  81 virtual bool pre( const Path& path, Instance& instance ) const = 0;
  82 /// \brief Called after traversing the last child-instance of 'instance'.
  83 virtual void post( const Path& path, Instance& instance ) const {
  84 }
  85 };
  86
  87 virtual ~Graph(){}
  88 /// \brief Returns the root-node of the graph.
  89 virtual Node& root() = 0;
  90 /// \brief Sets the root-node of the graph to be 'node'.
  91 virtual void insert_root( Node& root ) = 0;
  92 /// \brief Clears the root-node of the graph.
  93 virtual void erase_root() = 0;
  94 /// \brief Traverses all nodes in the graph depth-first, starting from the root node.
  95 virtual void traverse( const Walker& walker ) = 0;
  96 /// \brief Traverses all nodes in the graph depth-first, starting from 'start'.
  97 virtual void traverse_subgraph( const Walker& walker, const Path& start ) = 0;
  98 /// \brief Returns the instance at the location identified by 'path', or 0 if it does not exist.
  99 virtual scene::Instance* find( const Path& path ) = 0;
 100
 101 /// \brief Invokes all scene-changed callbacks. Called when any part of the scene changes the way it will appear when the scene is rendered.
 102 /// \todo Move to a separate class.
 103 virtual void sceneChanged() = 0;
 104 /// \brief Add a \p callback to be invoked when the scene changes.
 105 /// \todo Move to a separate class.
 106 virtual void addSceneChangedCallback( const SignalHandler& handler ) = 0;
 107
 108 /// \brief Invokes all bounds-changed callbacks. Called when the bounds of any instance in the scene change.
 109 /// \todo Move to a separate class.
 110 virtual void boundsChanged() = 0;
 111 /// \brief Add a \p callback to be invoked when the bounds of any instance in the scene change.
 112 virtual SignalHandlerId addBoundsChangedCallback( const SignalHandler& boundsChanged ) = 0;
 113 /// \brief Remove a \p callback to be invoked when the bounds of any instance in the scene change.
 114 virtual void removeBoundsChangedCallback( SignalHandlerId id ) = 0;
 115
 116 virtual TypeId getNodeTypeId( const char* name ) = 0;
 117 virtual TypeId getInstanceTypeId( const char* name ) = 0;
 118 };
 119
 120 class Traversable
 121 {
 122 public:
 123 STRING_CONSTANT( Name, "scene::Traversable" );
 124
 125 class Observer
 126 {
 127 public:
 128 /// \brief Called when a node is added to the container.
 129 virtual void insert( Node& node ) = 0;
 130 /// \brief Called when a node is removed from the container.
 131 virtual void erase( Node& node ) = 0;
 132 };
 133
 134 class Walker
 135 {
 136 public:
 137 /// \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.
 138 virtual bool pre( Node& node ) const = 0;
 139 /// \brief Called after traversing the last child-node of 'node'.
 140 virtual void post( Node& node ) const {
 141 }
 142 };
 143 /// \brief Adds a node to the container.
 144 virtual void insert( Node& node ) = 0;
 145 /// \brief Removes a node from the container.
 146 virtual void erase( Node& node ) = 0;
 147 /// \brief Traverses the subgraphs rooted at each node in the container, depth-first.
 148 virtual void traverse( const Walker& walker ) = 0;
 149 /// \brief Returns true if the container contains no nodes.
 150 virtual bool empty() const = 0;
 151 };
 152
 153 class Instantiable
 154 {
 155 public:
 156 STRING_CONSTANT( Name, "scene::Instantiable" );
 157
 158 class Observer
 159 {
 160 public:
 161 /// \brief Called when an instance is added to the container.
 162 virtual void insert( scene::Instance* instance ) = 0;
 163 /// \brief Called when an instance is removed from the container.
 164 virtual void erase( scene::Instance* instance ) = 0;
 165 };
 166
 167 class Visitor
 168 {
 169 public:
 170 virtual void visit( Instance& instance ) const = 0;
 171 };
 172
 173 /// \brief Returns a new instance uniquely identified by 'path'.
 174 virtual scene::Instance* create( const scene::Path& path, scene::Instance* parent ) = 0;
 175 /// \brief Calls Visitor::visit(instance) for each instance in the container.
 176 virtual void forEachInstance( const Visitor& visitor ) = 0;
 177 /// \brief Adds an instance to the container.
 178 virtual void insert( Observer* observer, const Path& path, scene::Instance* instance ) = 0;
 179 /// \brief Returns an instance removed from the container.
 180 virtual scene::Instance* erase( Observer* observer, const Path& path ) = 0;
 181 };
 182
 183 class Cloneable
 184 {
 185 public:
 186 STRING_CONSTANT( Name, "scene::Cloneable" );
 187
 188 /// \brief Returns a copy of itself.
 189 virtual scene::Node& clone() const = 0;
 190 };
 191 }
 192
 193 #include "modulesystem.h"
 194
 195 template<typename Type>
 196 class GlobalModule;
 197 typedef GlobalModule<scene::Graph> GlobalSceneGraphModule;
 198
 199 template<typename Type>
 200 class GlobalModuleRef;
 201 typedef GlobalModuleRef<scene::Graph> GlobalSceneGraphModuleRef;
 202
 203 inline scene::Graph& GlobalSceneGraph(){
 204         return GlobalSceneGraphModule::getTable();
 205 }
 206
 207 inline void AddSceneChangeCallback( const SignalHandler& handler ){
 208         GlobalSceneGraph().addSceneChangedCallback( handler );
 209 }
 210 inline void SceneChangeNotify(){
 211         GlobalSceneGraph().sceneChanged();
 212 }
 213
 214
 215
 216 #endif