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