This section assumes you have installed the szg software (including the sample applications contained in that package) by compiling (both "make" and "make demo"). You will understand the instructions better if you read the Cluster Mode chapter first, but, actually, these two sections can be studied in parallel. This section introduces you to the fault tolerance and flexibility of a Syzygy set-up. Components can appear, disappear, connect, disconnect, and reconnect in any order, which helps during the experimentation and debugging phases of application development.

This tutorial specifically avoids virtual computers in order to encourage freeform experimentation. However, please consider using them in your production environment.

If you run into problems running the tests that cannot be solved by the diagnostics listed, please see Troubleshooting the Distributed Operating System.

A Simple Test

One can run some simple tests without any configuration at all (beyond szg.conf). On any computer in the distributed system, type:

  hspace

A window should appear with a green spiderweb on a black background. If the window fails to launch, the only possibility is that the ports were misconfigured on the machine on which it executed. Attempt adjusting the ports block of the computer on which you ran it via dports. The first successfully launched instance of hspace is the "master". Subsequently launched instances will be "slaves", depending upon the master for information about navigation and the state of the world. Go ahead and launch hspace on other computers in the distributed system. You can quit the program by typing ESC in its window.

Next, on any computer in the system, type:

  inputsimulator

On that computer, a window will appear with some geometrical objects, the meaning of which is described in Input Simulator. Move the mouse in the resulting window with a button held down. The green spiderwebs should move in unison. If they do not move, the configuration of the computer on which the FIRST instance of hspace (the master) ran must be incorrect. Make sure that on that computer the network addresses are correct in the Syzygy config file. Furthermore, make sure that that computer can communicate with the computer running inputsimulator over one of those addresses.

The inputsimulator program has a server (for input device information) embedded in it. If it fails to launch, attempt adjusting the ports block of the computer on which you ran it via dports. If it launches, but the green lines in the hspace window do not move when the wireframe sphere moves, this is because the input device client embedded in hspace could not connect. Make sure the Syzygy config file on the computer running hspace has correct information and that the computer running inputsimulator is reachable via the first address listed in the Syzygy config file on the computer running hspace. If the latter is false, use daddinterface and ddelinterface to manipulate the config file on the computer running hspace. Then, upon killing and then restarting hspace, everything should work. NOTE: to quit inputsimulator, type ESC in its window.

Note that only one copy of inputsimulator will run at a given time. It offers a service (SZG_INPUT0), and the szgserver enforces that only a single component can offer a particular service. Try running multiple copies of it and observe the failure. On the other hand, try killing inputsimulator and restarting it on another computer in the distributed system. This will work, assuming that the computers in question are configured correctly, as discussed above. The components automatically reconnect and recreate a working application.

Note that when you kill the master instance of hspace, no motion of the inputsimulator will cause the slaves to move. This is because there now exists no master instance. However, the next hspace instance you launch will become the new master and everything will again work.

Database Parameters Example for Confidence Tests

While, as above, some of Syzygy's flavor can be experienced without specific configuration, more interesting effects require it. For instance, reading data files and constructing tiled displays require configuration. Here are some example parameters, in a format readable by the dbatch command. We made the following assumptions in creating this list:

For an explanation of how to get the configuration information into the Syzygy server (using dbatch), please see the System Configuration chapter. However, simply copying the XML from this documentation into a text file and issuing the command "dbatch the_text_file_name" should work.

<szg_config>
<param>
<name>left_side</name>
<value>
<szg_display>
 <szg_window>
   <size width="600" height="600" />
   <position x="50" y="50" />
   <szg_viewport_list viewmode="normal">
     <szg_camera>
       <szg_screen>
         <center x="0" y="0" z="-5" />
         <up x="0" y="1" z="0" />
         <dim width="20" height="10" />
         <normal x="0" y="0" z="-1" />
         <headmounted value="true" />
         <tile tilex="0" numtilesx="2" tiley="0" numtilesy="1" />
       </szg_screen>
     </szg_camera>
   </szg_viewport_list>
 </szg_window>
</szg_display>
</value>
</param>
<param>
<name>right_side</name>
<value>
<szg_display>
 <szg_window>
   <size width="600" height="600" />
   <position x="50" y="50" />
   <szg_viewport_list viewmode="normal">
     <szg_camera>
       <szg_screen>
         <center x="0" y="0" z="-5" />
         <up x="0" y="1" z="0" />
         <dim width="20" height="10" />
         <normal x="0" y="0" z="-1" />
         <headmounted value="true" />
         <tile tilex="1" numtilesx="2" tiley="0" numtilesy="1" />
       </szg_screen>
     </szg_camera>
   </szg_viewport_list>
 </szg_window>
</szg_display>
</value>
</param>
<param>
<name>whole_view</name>
<value>
<szg_display>
 <szg_window>
   <size width="600" height="600" />
   <position x="50" y="50" />
   <szg_viewport_list viewmode="normal">
     <szg_camera>
       <szg_screen>
         <center x="0" y="0" z="-5" />
         <up x="0" y="1" z="0" />
         <dim width="10" height="10" />
         <normal x="0" y="0" z="-1" />
         <headmounted value="true" />
         <tile tilex="1" numtilesx="1" tiley="0" numtilesy="1" />
       </szg_screen>
     </szg_camera>
   </szg_viewport_list>
 </szg_window>
</szg_display>
</value>
</param>
<assign>
slave1 SZG_RENDER texture_path /szg/rsc
slave1 SZG_RENDER text_path /szg/rsc/Text
slave1 SZG_SOUND path /szg/rsc
slave1 SZG_EXEC path /szg/bin/linux
slave1 SZG_DATA path /szg/data
slave1 SZG_DISPLAY0 name left_side
slave2 SZG_RENDER texture_path /szg/rsc
slave2 SZG_RENDER text_path /szg/rsc/Text
slave2 SZG_SOUND path /szg/rsc
slave2 SZG_EXEC path /szg/bin/linux
slave2 SZG_DATA path /szg/data
slave2 SZG_DISPLAY0 name right_side
control SZG_RENDER texture_path /szg/rsc
control SZG_RENDER text_path /szg/rsc/Text
control SZG_SOUND path /szg/rsc
control SZG_EXEC path /szg/bin/linux
control SZG_DATA path /szg/data
control SZG_DISPLAY0 name whole_view
</assign>
</szg_config>

Descriptions of parameters:

You'll have to alter the following for your setup:

The set-up outlined above assumes that the display computers will have monitors side by side. In this example, "slave1" is displaying the left half and "slave2" is displaying the right half. You can easily reverse this by swapping the SZG_DISPLAY0/name parameter values. Or you can set up a completely different type of display by changing the XML of the global parameters left_side and right_side.

WARNING

This file is being re-written. Information in the following section is out-of-date. In particular, the Syzygy Distributed Scene Graph is no longer supported.

Running the Distributed Graphics Confidence Test

These are the basic steps:

What should happen is that each execution of szgrender causes a black-filled window to open on the appropriate machine. When cosmos runs, each window should show a partial view of a set of rotating, concentric, highly colorful tori, along with a halo of rays that ryhtmically change length.

If you get an error "szgd found no file foo in the SZG_EXEC path", then you didn't set up the database properly in step 3. The executables in question need to be in SZG_EXEC/path.

The various demo programs, including cosmos, want to connect to a networked input device. See the Input Devices documentation page for an enumeration of the supported devices. For simplicity's sake, here we assume you'll control the demo using the Input Simulator, which translates mouse movements and keyboard presses into tracker-style events.

  dex control inputsimulator

Type dps on a member of the cluster and note the output. You can see everything running now. To kill the test:

   dkill control cosmos

The szgrender windows will go black again. You can execute cosmos on control again, and the tori will return. Note that you can also run any of these executables from the command line on the individual machines instead of via dex. To kill the other stuff,

   dkill slave1 szgrender
   dkill slave2 szgrender
   dkill control inputsimulator

You can also hear sound from many of the demos, assuming you've compiled with fmod support and have a sound card in "control". Try:

  dex control SoundRender

NOTE: the same parameters mentioned above will allow you to run everything on a single box. Typing:

  dex control szgrender
  dex control cosmos
  dex control inputsimulator

will bring everything up. Appropriate dkill's will bring everything down.

Running a Master/Slave Application

So far, you've seen how to run a distributed scene graph application. Let's now examine how to run a master/slave application (using dex, dkill, and configured screens). As mentioned above, in a master/slave application, seperate copies of the application run on each render node, with one application, the master, controlling the execution of the others.

We'll use the same three-machine configuration for this example, the difference being that one of the rendering machines, "slave1" will be running the master application (an unfortunate confusion in names), the other, "slave2", will be running the slave application, and "control" will be responsible for input and sound as before.

We can now run a master/slave application, like hspace (one of the included demos) as follows:

   dex slave1 hspace
   dex slave2 hspace

To stop the application:

   dkill slave1 hspace
   dkill slave2 hspace

To hear sound (assuming you've compiled w/ fmod support and have a sound card in "control"):

   dex control SoundRender

You can also run a master/slave application on a single box, just launch all components on, for instance, "control".