Doc/to_port/Cluster.dox

   1 #include <OSGConfig.h>
   2
   3 using namespace OSG;
   4
   5 /*! \defgroup GrpSystemCluster Cluster
   6     \ingroup GrpSystem
   7
   8     See \ref PageSystemCluster for details.
   9 */
  10
  11 /*! \page PageSystemCluster Cluster
  12
  13 Clustering
  14
  15 The clustering part of OpenSG is used to transfer FieldContainers over
  16 a network and to render an Image on an arbitrary number of
  17 computers. The replication of FieldContaienrs is implemented as an
  18 extension of the multithread aspect model of OpenSG.
  19
  20 \section PageSystemClusterRemoteAspect RemoteAspect
  21
  22 There are distinct field values for each thread. Changes between these
  23 fields are propagated when the changes stored in the changelist are
  24 applied to another aspect. The RemoteAspect class is used to transfer
  25 changes over a network connection to a number of remote computers. The
  26 RemoteAspect class has two methods for change distribution. Changes
  27 are sent with sendSync and received with receiveSync. It is important,
  28 that changes are transferred only once. The current changelist must be
  29 cleared before the next call of sendSync. In some situations it is
  30 useful to have a callback when a FieldContainer of a given type is
  31 created, changed ore destroyed. The methods registerCreated,
  32 registerChanged and registerDestroyed are used to register a
  33 functor. The ClusterServer uses this feature to be informed of new or
  34 changed ClusterWindows
  35
  36 \section PageSystemClusterWindow ClusterWindow
  37
  38 As there are many approaches to do rendering in a cluster (e.g. Sort-first,
  39 sort-middle, sort-last), OpenSG provides a base framework to implement special
  40 algorithms. Each algorithm is implemented in a class, derived from
  41 ClusterWindow. The idea of this window is, that a window describes the
  42 context, in which rendering is done. There is a GLUT-Window to redner with
  43 GLUT, X-Winow to render in an X11 environment and a ClusterWindow to render in
  44 a cluster. When ClusterWindow::init is called, the a connection is established
  45 to all servers stored in the servers field. This connection is used to
  46 transfer changes to all servers. As all fieldcontainers are synced with the
  47 RemoteAspect to all cluster node, there is an instance of the ClusterWindow on
  48 all cluster-nodes. The ClusterWindow has a couple of virtual methods that are
  49 called for the client and for the servers. In this context a server is a
  50 renderer and the client is the application.
  51
  52 On the client side the following methods are called by the
  53 ClusterWindow, when ClusterWindow::render is called.
  54
  55
  56 \li ClientInit: Is called when ClusterWindow::render is called for the first time
  57
  58 \li clientPreSync: Is called before the changes in the current changelist are transferred to the servers
  59
  60 \li clientRender: Is called after chanelist sync.
  61
  62 \li ClientSwap: Called after clientRender and serverRender was called
  63
  64 On the server side the following methods are called when ClusterServer::render is called. The ClusterServer is described in the following section.
  65
  66 \li ServerInit: Called after an initial sync.
  67
  68 \li ServerRender: Called after the changelist sync.
  69
  70 \li ServerSwap: Called after clientRender and serverRender
  71
  72
  73 \section PageSystemClusterServer ClusterServer
  74
  75 A ClusterServer is responsible for server side rendering. Each server
  76 has its unique name. If a server request with this name is received, a
  77 connection to the client is established. After this all changes to the
  78 scenegraph from the client are received through the RemoteAspect.
  79 When a new ClusterWindow is found in the data stream, server side
  80 rendering is initialized. As a cluster window has no GL context, you
  81 have to initialize a GLUT, Qt, X or WIN32 window with a valid GL
  82 context. This window is passed to ClusterWindow::serverRender and
  83 ClusterWindow::serverSwap. The second parameter of the ClusterServer
  84 constructor is a name. With this name the client finds the
  85 servers. The third parameter is the type of connection you want to
  86 use. e.g. StreamSocket or Multicast. The last parameter is an address
  87 string. If address is an empty string, then a default address is
  88 used. With the method server->start, the server starts waiting for
  89 incoming connections. In your rendering callback (for GLUT
  90 glutIdelFunc or glutDisplayFunc) you have to call server->render with
  91 a valid render action.
  92
  93 \section PageSystemClusterMultiDisplayWindow MultiDisplayWindow
  94
  95 The MultiDisplayWindow is derived from ClusterWindow. It is used to
  96 render one virtual window on a number of cluster servers. The whole
  97 window is split in equal sized regions. Each region is assigned to one
  98 server. With the fields hServers and vServers it is possible to set
  99 the number of rows and columns to which the whole window is split. For
 100 example if you want to drive a wall with 9 projectors you have to
 101 assign the name of 9 rendering servers to the servers field and set
 102 hServers and vServers to 3. The MultiDisplayWindow can have an
 103 arbitrary number of viewports. If a viewport is invisible on a server,
 104 this viewport is ignored for this server.  With this it is possible to
 105 use the MultiDisplayWindow for more complicated setups then a tiled
 106 wall.
 107
 108 If you want to drive a cave, you could set the servers to six cave rendering servers. Then you have to set hServers to 6 and vServers to 1. For each cave side, assign one viewport with the following size settings:
 109 <pre>
 110 vp0->setSize(     0,0, 1.0/6 ,1)
 111 vp1->setSize( 1.0/6,0, 2.0/6 ,1)
 112 vp2->setSize( 2.0/6,0, 3.0/6 ,1)
 113 vp3->setSize( 3.0/6,0, 4.0/6 ,1)
 114 vp4->setSize( 4.0/6,0, 5.0/6 ,1)
 115 vp5->setSize( 5.0/6,0, 6.0/6 ,1)
 116 </pre>
 117 If you have a resolution of 1024x1024 on each cave wall, you have to
 118 set the multiDisplayWindow->setSize(1024*6,1024). The
 119 MultiDisplayWindow assigns each viewport to one rendering
 120 server. After this, you have to setup the camera parameters for each
 121 cave wall. This is done with camera decorators e.g. the
 122 ShearedStereoCameraDecorator.
 123
 124 Example client and server
 125
 126 There are two test programs that can be used to setup a test cluster
 127 environment. testClusterServer hast to be started on each  rendering
 128 server.
 129
 130 <pre>
 131 testClusterServer -m MyServer1
 132 </pre>
 133
 134 This starts a server with the name MyServer1 that uses Multicast for
 135 communication. A simple scene viewer is started with:
 136
 137 <pre>
 138 testClusterServer -m MyServer1 MyServer2 -fscene.wrl
 139 </pre>
 140
 141 The client tries to connect to the servers MyServer1 and MyServer2. testClusterClient opens a local window for navigation.
 142
 143 */